home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1998 November / Freeware November 1998.img / dist / fw_plotutils.idb / usr / freeware / info / plotutils.info.z / plotutils.info (.txt)
GNU Info File  |  1998-10-27  |  333KB  |  6,410 lines
  1. This is Info file plotutils.info, produced by Makeinfo version 1.68
  2. from the input file plotutils.texi.
  3. INFO-DIR-SECTION GNU Plotting Utilities
  4. START-INFO-DIR-ENTRY
  5. * Plotting utilities: (plotutils).      GNU plotting utilities
  6. * graph: (plotutils)graph Invocation.   Plot datasets, possibly in real time
  7. * plot: (plotutils)plot Invocation.     Convert and display plot files
  8. * tek2plot: (plotutils)tek2plot Invocation.   Translate legacy Tektronix data
  9. * plotfont: (plotutils)plotfont Invocation.   Plot character maps of fonts
  10. * spline: (plotutils)spline Invocation. Interpolate between points in datasets
  11. * ode: (plotutils)ode Invocation.       Integrate differential equations
  12. * libplot: (plotutils)libplot.          A library for 2-D vector graphics
  13. * Appendices: (plotutils)Appendices.    More info on the plotting utilities
  14. END-INFO-DIR-ENTRY
  15.    This file documents version 2.1.4 of the GNU plotting utilities
  16. package, including GNU libplot 1.4
  17.    Copyright (C) 1989-1998 Free Software Foundation, Inc.
  18.    Permission is granted to make and distribute verbatim copies of this
  19. manual provided the copyright notice and this permission notice are
  20. preserved on all copies.
  21.    Permission is granted to copy and distribute modified versions of
  22. this manual under the conditions for verbatim copying, provided that
  23. the entire resulting derived work is distributed under the terms of a
  24. permission notice identical to this one.
  25.    Permission is granted to copy and distribute translations of this
  26. manual into another language, under the above conditions for modified
  27. versions, except that this permission notice may be stated in a
  28. translation approved by the Foundation.
  29. File: plotutils.info,  Node: Top,  Next: Plotutils Intro,  Prev: (dir),  Up: (dir)
  30.    This is the documentation for version 2.1.4 of the GNU plotting
  31. utilities package, including GNU libplot 1.4.  The package consists of
  32. programs and functions for data plotting and vector graphics.
  33. * Menu:
  34. * Plotutils Intro::     GNU plotting utilities
  35. * graph::               graph, a program for plotting datasets
  36. * plot::                plot, a plot format conversion program
  37. * tek2plot::            tek2plot, a translator for legacy Tektronix files
  38. * plotfont::            plotfont, a program for plotting font character maps
  39. * spline::              spline, an interpolation program
  40. * ode::                 ode, a differential equation integrator
  41. * libplot::             A library for device-independent 2-D vector graphics
  42. * Appendices::          Additional Information
  43. File: plotutils.info,  Node: Plotutils Intro,  Next: graph,  Prev: Top,  Up: Top
  44. The GNU Plotting Utilities
  45. **************************
  46.    The GNU plotting utilities currently consist of seven user-level
  47. programs: `graph', `plot', `tek2plot', `plotfont', `spline', `ode', and
  48. `double'.  Distributed along with them is GNU `libplot', a function
  49. library for device-independent two-dimensional vector graphics,
  50. including vector graphics animations under the X Window System.
  51.    `graph' is a program for plotting two-dimensional scientific data.
  52. It reads one or more data files containing datasets, and outputs a plot.
  53. The plot can be directed to a display device or to a file.  Six
  54. different display types or output formats are supported.  The
  55. corresponding commands are `graph -T X', `graph -T ps', `graph -T fig',
  56. `graph -T hpgl', `graph -T tek', and `graph'.
  57.    `graph -T X' pops up a window on an X Window System display, and
  58. draws the plot in it.  `graph -T ps' produces a plot in encapsulated
  59. Postscript format that may be included in another document, edited with
  60. the `idraw' drawing editor, or sent directly to a printer.  `graph -T
  61. fig' produces output that may be displayed and edited with the `xfig'
  62. drawing editor.  `graph -T hpgl' produces a Hewlett-Packard Graphics
  63. Language (HP-GL or HP-GL/2) plot that may be sent to a Hewlett-Packard
  64. LaserJet printer or plotter, or included in another document.  `graph
  65. -T tek' produces output that may be displayed on a Tektronix 4014
  66. terminal or emulator.  `graph' without a `-T' option (referred to as
  67. `raw `graph'') produces output in a device-independent format,
  68. a so-called GNU graphics metafile.  This metafile may be translated
  69. into other formats.
  70.    `graph' can read datasets in both ASCII and binary format, and
  71. datasets in the `table' format produced by the plotting program
  72. `gnuplot'.  It produces a plot with or without axes and labels.  You
  73. may specify labels and ranges for the axes, and the size and position
  74. of the plot on the display.  The labels may contain subscripts and
  75. subscripts, Greek letters, and other special symbols; there is also
  76. support for Cyrillic script (i.e., Russian) and Japanese.  You may
  77. specify the type of plotting symbol used for each dataset, and such
  78. parameters as the style and thickness of the line (if any) used to
  79. connect points in a dataset.  The plotting of filled regions is
  80. supported, as is the drawing of error bars.  `graph' provides full
  81. support for multiplotting.  With a single invocation of `graph', you
  82. may produce a plot consisting of many sub-plots, either side by side or
  83. inset.  Each sub-plot will have its own axes and data.
  84.    `graph -T X', `graph -T tek', and raw `graph' have a feature which
  85. most plotting programs do not have.  They can accept input from a pipe,
  86. and plot data points in real time.  For this to occur, the user must
  87. specify ranges for both axes, so that `graph' does not need to wait
  88. until the end of the input before determining them.
  89.    The `plot' program is a so-called plot filter.  It can translate GNU
  90. graphics metafiles (produced for example by raw `graph') into the six
  91. supported output formats.  The corresponding commands are `plot -T X',
  92. `plot -T ps', `plot -T fig', `plot -T hpgl', `plot -T tek', and `plot'.
  93. The `plot' program is useful if you wish to produce output in several
  94. different formats while invoking `graph' only once.  It is also useful
  95. if you wish to translate files in the traditional `plot(5)' format
  96. produced by, e.g., the non-GNU versions of `graph' provided with some
  97. operating systems.  GNU metafile format is compatible with the
  98. traditional `plot(5)' format.
  99.    The `tek2plot' program can translate from Tektronix format to any of
  100. the abovementioned output formats.  The corresponding commands are
  101. `tek2plot -T X', `tek2plot -T ps', `tek2plot -T fig', `tek2plot -T
  102. hpgl', and `tek2plot'.  `tek2plot' is useful if you have a legacy
  103. application that produces drawings in Tektronix format.
  104.    The `plotfont' program is a simple utility that displays a character
  105. map for any font that is available to `graph', `plot', or `tek2plot'.
  106. If the `-T X', `-T ps', or `-T fig' options are used, the 35 standard
  107. Postscript fonts are available, and if the `-T hpgl' option is used,
  108. the 45 standard PCL 5 fonts are available.  A set of 22 Hershey vector
  109. fonts, including Cyrillic fonts and a Japanese font, is always
  110. available.  When producing output for an X Window System display, any
  111. of these programs can use scalable X fonts.
  112.    Among the other GNU plotting utilities, `spline' does spline
  113. interpolation of scalar or vector-valued data.  It normally uses either
  114. cubic spline interpolation or exponential splines in tension, but like
  115. `graph' it can function as a real-time filter under some circumstances.
  116. Besides splining datasets, it can construct curves, either open or
  117. closed, through arbitrarily chosen points in d-dimensional space.
  118. `ode' provides the ability to integrate an ordinary differential
  119. equation or a system of ordinary differential equations, when provided
  120. with an explicit expression for each equation.  It supplements the
  121. plotting program `gnuplot', which can plot functions but not integrate
  122. ordinary differential equations.  The final plotting utility, `double',
  123. is a filter for converting, scaling and cutting binary or ASCII data
  124. streams.  It is still under development and is not yet documented.
  125.    Distributed along with the plotting utilities is GNU `libplot', the
  126. function library for device-independent two-dimensional vector graphics
  127. on which `graph', `plot', `tek2plot', and `plotfont' are based.
  128. `libplot' can draw graphics on X Window System displays, and perform
  129. smooth, double-buffered animation.  It can also generate graphical
  130. output in any of five additional formats.  This includes (1) output in
  131. Postscript format that may be included in another document, edited with
  132. the `idraw' drawing editor, or sent directly to a printer, (2) output
  133. that may be displayed and edited with the `xfig' drawing editor,
  134. (3) output in HP-GL or HP-GL/2 format that may be sent to a
  135. Hewlett-Packard LaserJet printer or plotter, (4) output that may be
  136. displayed on a Tektronix 4014 terminal or emulator, and (5) output in
  137. the device-independent GNU graphics metafile format.
  138.    `libplot' can draw such objects as lines, open and closed polylines,
  139. arcs (both circular and elliptic), circles and ellipses, points, marker
  140. symbols, and text strings.  The filling of objects other than points,
  141. marker symbols, and text strings is supported (fill color, as well as
  142. pen color, can be set arbitrarily).  The support for drawing text
  143. strings is extensive.  The X Window System, Postscript, and `xfig'
  144. drivers support the 35 standard Postscript fonts, and the HP-GL/2
  145. driver supports the 45 standard PCL 5 fonts.  All drivers, including
  146. the Tektronix and metafile drivers, support a set of 22 Hershey vector
  147. fonts.  Text strings may include subscripts and superscripts, and may
  148. include characters chosen from more than one font in a typeface.  Many
  149. non-alphanumeric characters may be included.  The entire collection of
  150. over 1700 `Hershey glyphs' digitized by Allen V. Hershey at the U.S.
  151. Naval Surface Weapons Center, which includes many curious symbols, is
  152. built into `libplot'.  Japanese text strings in the so-called EUC
  153. (Extended Unix Code) format can be also be drawn.  Such strings may
  154. include both syllabic characters (Hiragana and Katakana) and
  155. ideographic characters (Kanji).  A library of over 600 Japanese Kanji
  156. digitized by Dr. Hershey is built into `libplot'.
  157.    The drawing editors `idraw' and `xfig' are not distributed along
  158. with the GNU plotting utilities.  However, they are free software, and
  159. you may readily obtain them elsewhere (*note Auxiliary Software::.).
  160. File: plotutils.info,  Node: graph,  Next: plot,  Prev: Plotutils Intro,  Up: Top
  161. The `graph' Application
  162. ***********************
  163.    Each invocation of `graph' reads one or more datasets from files
  164. named on the command line or from standard input, and prepares a plot.
  165. There are many command-line options for adjusting the visual appearance
  166. of the plot.  The following sections explain how to use the most
  167. frequently used options, by giving examples.
  168. * Menu:
  169. * Simple Examples::     Simple examples using graph
  170. * Non-Square Plots::    Changing the aspect ratio of a plot
  171. * Multiple Datasets::   Preparing a plot from more than one dataset
  172. * Multiplotting::       Multiple plots on a single page
  173. * Data Formats::        Reading binary and other data formats
  174. * graph Invocation::    Command-line options
  175. File: plotutils.info,  Node: Simple Examples,  Next: Non-Square Plots,  Prev: graph,  Up: graph
  176. Simple examples using `graph'
  177. =============================
  178.    By default, `graph' reads ASCII data from the files specified on the
  179. command line, or from standard input if no files are specified.  The
  180. data are pairs of numbers, interpreted as the x and y coordinates of
  181. data points:
  182.      0.0  0.0
  183.      1.0  0.2
  184.      2.0  0.0
  185.      3.0  0.4
  186.      4.0  0.2
  187.      5.0  0.6
  188. Data points do not need to be on different lines, nor do the x and y
  189. coordinates of a data point need to be on the same line.  However,
  190. there should be no blank lines in the input if it is to be viewed as
  191. forming a single dataset.
  192.    To plot such a dataset with `graph', you could do
  193.      graph -T ps ascii_data_file > plot.ps
  194. or equivalently
  195.      graph -T ps < ascii_data_file > plot.ps
  196. This will produce an encapsulated Postscript file `plot.ps', which you
  197. may include in another document, display on a screen, or send directly
  198. to a printer.  (The `--page-size' option, or the `PAGESIZE' environment
  199. variable, specifies the size of the printed page.  The default is
  200. "letter", i.e., 8.5in by 11in, but "a4" or other ISO or ANSI page sizes
  201. can be specified instead.)
  202.    You may also do
  203.      graph -T fig < ascii_data_file > plot.fig
  204. to produce a file `plot.fig' that you may edit with the the `xfig'
  205. drawing editor, or
  206.      graph -T hpgl < ascii_data_file > plot.plt
  207. to produce a file `plot.plt' in the Hewlett-Packard Graphics Language
  208. (HP-GL/2) that you may send to a Hewlett-Packard LaserJet printer or
  209. plotter.
  210.    You may use `graph -T X' to pop up a window on an X Window System
  211. display, and display the plot in it.  For that, you would do
  212.      graph -T X < ascii_data_file
  213. If you use `graph -T X', no output file will be produced; only a
  214. window.  The window will vanish if you type `q' or click your mouse
  215. in it.
  216.    You may also use `graph -T tek', to display a plot on a device that
  217. can emulate a Tektronix 4014 graphics terminal.  `xterm', the X Window
  218. System terminal emulator, can do this.  Within an `xterm' window, you
  219. would do
  220.      graph -T tek < ascii_data_file
  221. `xterm' normally emulates a VT100 terminal, but when this command is
  222. issued from within it, it will pop up a second window (a `Tektronix
  223. window') and draw the plot in it.  The Japanese terminal emulator
  224. `kterm' should be able to do the same, provided that it is correctly
  225. installed.  Another piece of software that can emulate a Tektronix 4014
  226. terminal is the MS-DOS version of `kermit'.
  227.    `graph' may behave differently depending on the environment in which
  228. it is invoked.  We have already mentioned the `PAGESIZE' environment
  229. variable, which affects the operation of `graph -T ps', `graph -T fig',
  230. and `graph -T hpgl'.  The `DISPLAY' and `BITMAPSIZE' environment
  231. variables affect the operation of `graph -T X', and the `TERM'
  232. environment variable affects the operation of `graph -T tek'.  There
  233. are also several environment variables that affect the operation of
  234. `graph -T hpgl'.  For a complete discussion of the effects of the
  235. environment on `graph', see *Note graph Environment::.  The following
  236. remarks apply irrespective of which display type is specified.
  237.    By default, successive points in the dataset are joined by solid line
  238. segments, which form a polygonal line or polyline that we call simply a
  239. `line'.  You may choose the style of line (the `linemode') with the
  240. `-m' option:
  241.      graph -T ps -m 2 < ascii_data_file > plot.ps
  242. Here `-m 2' indicates that linemode #2 should be used.  If the dataset
  243. is rendered in monochrome, which is the default, the line can be drawn
  244. in one of five distinct styles.  Linemodes #1 through #5 signify solid,
  245. dotted, dotdashed, shortdashed, and longdashed; thereafter the sequence
  246. repeats.  If the `-C' option is used, the dataset will be rendered in
  247. color.  For colored datasets, the line can be drawn in one of 25
  248. distinct styles.  Linemodes #1 through #5 signify red, green, blue,
  249. magenta, and cyan; all are solid.  Linemodes #6 through #10 signify the
  250. same five colors, but dotted rather than solid.  Linemodes #11 through
  251. #16 signify the same five colors, but dotdashed, and so forth.  After
  252. linemode #25, the sequence repeats.  Linemode #0, irrespective of
  253. whether the rendering is in monochrome or color, means that the line is
  254. not drawn.
  255.    If you wish to *fill* the polygon bounded by the line (i.e., shade
  256. it, or fill it with a solid color), you may use the `-q' option.  For
  257. example,
  258.      echo .1 .1 .1 .9 .9 .9 .9 .1 .1 .1 | graph -T ps -C -m 1 -q 0.3 > plot.ps
  259. will plot a square region with vertices (0.1,0.1), (0.1,0.9), (0.9,0.9),
  260. and (0.9,0.1).  The repetition of the first vertex (0.1,0.1) at the end
  261. of the sequence of vertices ensures that the square will be closed: all
  262. four segments of its boundary will be drawn.  The square will be drawn
  263. in red (since the colored version of linemode #1 is requested).  The
  264. interior of the square will be filled with red to an intensity of 30%,
  265. as the `-q 0.3' option indicates.  If the intensity were zero, the
  266. region would be filled with white, and if it were 1.0, the region would
  267. be filled with solid color.  If the intensity were negative, the region
  268. would be unfilled, or transparent (the default).
  269.    You may choose the width of the line, whether it is filled or not, by
  270. using the `-W' option.  For example, `-W 0.01' means that the line
  271. should have a width equal to 0.01 times the width of the display.
  272. Also, you may put symbols at each data point along the line by doing,
  273. for example,
  274.      graph -T ps -S 3 0.1 < ascii_data_file > plot.ps
  275. where the first argument 3 indicates which symbol to plot.  The optional
  276. second argument 0.1 specifies the symbol size as a fraction of the size
  277. of the `plotting box': the square within which the plot is drawn.
  278. Symbol #1 is a dot, symbol #2 is a plus sign, symbol #3 is an asterisk,
  279. symbol #4 is a circle, symbol #5 is a cross, and so forth.  (*Note
  280. Marker Symbols::.)  Symbols 1 through 31 are the same for all display
  281. types, and the color of a symbol will be the same as the color of the
  282. line it is plotted along.
  283.    Actually, you would probably not want to plot symbols at each point
  284. in the dataset unless you turn off the line joining the points.  For
  285. this purpose, the `negative linemode' concept is useful.  A line whose
  286. linemode is negative is not visible; however, any symbols plotted along
  287. it will have the color associated with the corresponding positive
  288. linemode.  So, for example,
  289.      graph -T ps -C -m -3 -S 4 < ascii_data_file > plot.ps
  290. will plot a blue circle at each data point.  The circles will not be
  291. joined by line segments.  By adding the optional second argument to the
  292. `-S' option, you may adjust the size of the circles.
  293.    `graph' will automatically generate abscissa (i.e., x) values for
  294. you if you use the `-a' option.  If this option is used, no abscissa
  295. values should be given in the data file.  The data points will be taken
  296. to be regularly spaced along the abscissa.  The two arguments following
  297. `-a' on the command line will be taken as the sampling interval and the
  298. abscissa value of the first data point.  If they are absent, they
  299. default to 1.0 and 0.0 respectively.  For example, the command
  300.      echo 0 1 0 | graph -T ps -a > plot.ps
  301. produces exactly the same plot  as
  302.      echo 0 0 1 1 2 0 | graph -T ps > plot.ps
  303.    `graph' will plot data with error bars, if the `-I e' option is
  304. specified.  If it is, the dataset should consist of triples (x,y,error)
  305. rather than pairs (x,y).  A vertical error bar of the appropriate
  306. length will be plotted at each data point.  You may plot a symbol at
  307. each data point, along with the error bar, by using the `-S' option in
  308. the usual way.  The symbol will be the same for each point in the
  309. dataset.  You may use the `-a' option in conjunction with `-I e', if
  310. you wish.  If you do, the dataset should contain no abscissa (i.e., x)
  311. values.
  312.    By default the limits on the x and y axes, and the spacing between
  313. the labeled ticks on each axis, are computed automatically.  You may
  314. wish to set them manually.  You may accomplish this with the `-x' and
  315. `-y' options.
  316.      echo 0 0 1 1 2 0 | graph -T ps -x -1 3 -y -1 2 > plot.ps
  317. will produce a plot in which the x axis extends from -1 to 3, and the y
  318. axis from -1 to 2.  By default, `graph' tries to place about six
  319. numbered ticks on each axis.  By including an optional third argument
  320. to either `-x' or `-y', you may manually set the spacing of these
  321. ticks, also.  For example, using `-y -1 2 1' rather than `-y -1 2' will
  322. produce a y axis with labeled ticks at -1, 0, 1, and 2, rather than at
  323. the locations that `graph' would choose by default.  In general, if a
  324. third argument is present then labeled ticks will be placed at each of
  325. its integer multiples.
  326.    To make an axis logarithmic, you may use the `-l' option.  For
  327. example,
  328.      echo 1 1 2 3 3 1 | graph -T ps -l x > plot.ps
  329. will produce a plot in which the x axis is logarithmic, but the y axis
  330. is linear.  To make both axes logarithmic, you would use `-l x -l y'.
  331. By default, the upper and lower limits on a logarithmic axis are powers
  332. of ten, and the tick marks at these powers of ten, and no other tick
  333. marks, are labeled.  If you need more labeled ticks on a logarithmic
  334. axis, you should specify a tick spacing manually.  For example, `-l x
  335. -x 1 9 2' will produce a plot in which the x axis is logarithmic and
  336. extends from 1 to 9.  Labeled ticks will be located at each integer
  337. multiple of 2, i.e., at 2, 4, 6, and 8.
  338.    You may label the x and y axes with the `-X' and `-Y' options,
  339. respectively.  For example,
  340.      echo 1 1 2 3 3 1 | graph -T ps -l x -X "A Logarithmic Axis" > plot.ps
  341. will label the log axis in the preceding example.  By default the label
  342. for the y axis (if any) will be rotated 90 degrees, unless you use the
  343. `--toggle-rotate-y-label' option.  You may specify a `top label', or
  344. title for the plot, by using the `-L' option.  Doing, for example,
  345.      echo 1 1 2 3 3 1 | graph -T ps -l x -L "A Simple Example" > plot.ps
  346. will produce a plot with a title on top.
  347.    The size of the x axis and y axis labels is specified with the `-f'
  348. option, and the size of the title is specified with the
  349. `--title-font-size' option.  For example,
  350.      echo 1 1 2 3 3 1 | graph -T ps -X "Abscissa" -f 0.1 > plot.ps
  351. will produce a plot in which the font size of the x axis label, and
  352. each of the numerical tick labels, is very large (0.1 times the size of
  353. the plotting box, i.e., the square within which the plot is drawn).
  354.    The font in which the labels specified with the `-X', `-Y', and `-L'
  355. options are drawn can be specified with the `-F' option.  For example,
  356. `-F Times-Roman' will make the labels appear in Times-Roman instead of
  357. the default font (which is Helvetica, unless `-T hpgl' or `-T tek' is
  358. specified).  Font names are case-insensitive, so `-F times-roman' will
  359. work equally well.  The available fonts include 35 Postscript fonts
  360. (for all variants of `graph' other than `graph -T hpgl' and `graph -T
  361. tek'), 45 PCL 5 fonts (for `graph -T hpgl'), and 22 Hershey vector
  362. fonts.  The Hershey fonts include HersheyCyrillic, for Russian, and
  363. HersheyEUC, for Japanese.  For a discussion of the available fonts, see
  364. *Note Text Fonts::.  The `plotfont' utility will produce a character
  365. map of any available font.  *Note plotfont::.
  366.    The format of the labels drawn with the `-X', `-Y', and `-L' options
  367. may be quite intricate.  Subscripts, superscripts, square roots, and
  368. switching fonts within a typeface are all allowed.  The above examples
  369. do not illustrate this, but for details, see *Note Text String Format::.
  370.    Each of the preceding examples produced a plot containing the default
  371. sort of grid (a square box, with ticks and labels drawn along its lower
  372. edge and its left edge).  There are actually several sorts of grid you
  373. may request.  The `-g 0', `-g 1', `-g 2', and `-g 3' options yield
  374. successively fancier grids.  What they yield, respectively, is no grid
  375. at all, a pair of axes with ticks and labels, a square box with ticks
  376. and labels, and a square box with ticks, labels, and grid lines.  As
  377. you can see, `-g 2' is the default.  There is also a `-g 4' option,
  378. which yields a slightly different sort of grid: a pair of axes that
  379. cross at the origin.  This last sort of grid is useful if the x or y
  380. coordinates of the data points you are plotting are both positive and
  381. negative.
  382. File: plotutils.info,  Node: Non-Square Plots,  Next: Multiple Datasets,  Prev: Simple Examples,  Up: graph
  383. Non-square and displaced plots
  384. ==============================
  385.    To alter the linear dimensions of a plot, and also to position it in
  386. a different part of your display, you could do something like
  387.      graph -T ps -h .3 -w .6 -r .1 -u .1 < ascii_data_file > plot.ps
  388. Here the `-h' and `-w' options specify the height and width of the
  389. plotting box, and the `-r' and `-u' options indicate how far up and to
  390. the right the lower left corner of the plotting box should be
  391. positioned.  All dimensions are expressed as fractions of the size of
  392. the graphics display, which by convention is a square.  By default, the
  393. height and width of the plotting box equal 0.6, and the `upward shift'
  394. and the `rightward shift' equal 0.2.  So the above example will produce
  395. a plot that is half as tall as usual.  Compared to its usual position,
  396. the plot will be shifted slightly downward and to the left.
  397.    The `graphics display', within which the plotting box is located, is
  398. an abstraction.  For `graph -T X', it is a square window on an
  399. X display, the size of which can be set by using the `--bitmap-size'
  400. option, or by setting the `BITMAPSIZE' environment variable.  For
  401. `graph -T tek', it is a square region occupying the central part of a
  402. Tektronix display.  (Tektronix displays are 4/3 times as wide as they
  403. are high.)  For `graph -T ps', by default it is a square region
  404. centered on an 8.5in by 11in page (US letter size), occupying the full
  405. width of the page with allowance being made for margins.  For `graph -T
  406. fig', by default it is a square region of the same size, positioned in
  407. the upper left corner of an `xfig' display.  For `graph -T hpgl',
  408. by default it is a square region of the same size, with position and
  409. orientation on the page being controlled by environment variables.  The
  410. page size used by `graph -T ps', `graph -T fig', and `graph -T hpgl'
  411. can be set by using the `--page-size' option, or by setting the
  412. environment variable `PAGESIZE'.  For example, setting `PAGESIZE' to
  413. "a4" would position the graphics display appropriately on an A4-size
  414. page (21cm by 29.7cm).
  415.    Changing the width of the plotting box may have unforeseen
  416. consequences.  A number of command-line options specify sizes or
  417. dimensions as fractions of the width of the plotting box.  For example,
  418. `-S 3 .01' specifies that the plotting symbols for the following dataset
  419. should be of type #3, and should have a fractional size equal to 0.01.
  420. If the `-w' option is employed to widen or narrow the plot, such
  421. dimensions or sizes will scale in tandem.  That is presumably the right
  422. thing to do, but may be slightly disconcerting.
  423. File: plotutils.info,  Node: Multiple Datasets,  Next: Multiplotting,  Prev: Non-Square Plots,  Up: graph
  424. Preparing a plot from more than one dataset
  425. ===========================================
  426.    It is frequently the case that several datasets need to be displayed
  427. on the same plot.  If so, you may wish to distinguish the points in
  428. different datasets by joining them by lines of different types, or by
  429. using plotting symbols of different types.
  430.    A more complicated example would be the following.  You may have a
  431. file containing a dataset that is the result of experimental
  432. observations, and a file containing closely spaced points that trace
  433. out a theoretical curve.  The second file is a dataset in its own
  434. right.  You would presumably plot it with line segments joining
  435. successive points, so as to trace out the theoretical curve.  But the
  436. first dataset, resulting from experiment, would be plotted without such
  437. line segments.  In fact, a plotting symbol would be plotted at each of
  438. its points.
  439.    These examples, and others like them, led us to define a set of seven
  440. *attributes* which define the way in which a dataset should be plotted.
  441. These attributes, which can be set by command-line options, are the
  442. following.
  443.   1. color/monochrome
  444.   2. linemode
  445.   3. linewidth
  446.   4. symbol type
  447.   5. symbol size
  448.   6. symbol font name
  449.   7. fill fraction
  450. Color/monochrome (a choice of one or the other) is the simplest.  This
  451. choice is toggled with the `-C' option.  The `linemode' (i.e., line
  452. style) specifies how the line segments joining successive points should
  453. be drawn; it is specified with the `-m' option.  Linemode #0 means no
  454. linemode at all, for example.  `Linewidth' is self-explanatory; it is
  455. specified with the `-W' option. `Symbol type' and `symbol size', which
  456. are specified with the `-S' option, specify the symbol plotted at each
  457. point of the dataset.  `Symbol font name' refers to the font from which
  458. plotting symbols #32 and above, which are taken to be characters rather
  459. than geometric symbols, are selected.  It is set with the
  460. `--symbol-font-name' option, and is relevant only if `-S' is used to
  461. request such special plotting symbols. Finally, the polygonal line
  462. joining the points in a dataset may be *filled*, to create a filled or
  463. shaded polygon.  The `fill fraction' is set with the `-q' option.
  464. A negative fill fraction means no fill, or transparent; zero means
  465. white, and 1.0 means solid, or fully colored.
  466.    The preceding seven attributes refer to the way in which datasets are
  467. plotted.  Datasets may also differ from one another in the way in which
  468. they are read from files.  The dataset(s) in a file may or may not
  469. contain error bars, for example.  If a file contains data with error
  470. bars, the `-I e' option should occur on the command line before the
  471. file name.  (The `-I' option specifies the input format for the
  472. following files.)
  473.    The following illustrates how datasets in three different input files
  474. could be plotted simultaneously.
  475.      graph -T ps -m 0 -S 3 file_1 -C -m 3 file_2 -C -W 0.02 file_3 > output.ps
  476. The dataset in `file_1' will be plotted in linemode #0, so successive
  477. points will not be joined by lines.  But symbol #3 (an asterisk) will
  478. be plotted at each point.  The dataset in `file_2' will be plotted in
  479. color, and linemode #3 will be used.  In color plotting, linemode #3 is
  480. interpreted as a solid blue line.  The second `-C' on the command line
  481. turns off color for `file_3'.  The points in the third dataset will be
  482. joined by a black line of width 0.02, as a fraction of the width of the
  483. graphics display.
  484.    The above command line could be made even more complicated by
  485. specifying additional options (e.g., `-q' or `-I') before each file.
  486. In fact the command line could also include such standard options as
  487. `-x' or `-y', which specify the range of each axis.  Such options,
  488. which refer to the plot as a whole rather than to individual datasets,
  489. should appear before the first file name.  For example, you could do
  490.      graph -T ps -x 0 1 0.5 -m 0 -S 3 file_1 -C -m 3 file_2 > output.ps
  491. Note that it is possible to include the special file name `-', which
  492. refers to standard input, on the command line.  So you may produce a
  493. plot in part from files, and in part from input that is piped to
  494. `graph' from another program.
  495.    Each input file may include more than one dataset.  If so, the
  496. command line options preceding a file on the command line will take
  497. effect for all datasets in that file.  There are two exceptions to
  498. this.  By default, the linemode is incremented (`bumped') from one
  499. dataset to the next.  This feature is usually quite convenient.  For
  500. example, if you do
  501.      graph -T ps -m 3 file_1 > output.ps
  502. the first dataset in `file_1' will appear in linemode #3, the second in
  503. linemode #4, etc.  In fact if you do
  504.      graph -T ps file_1 file_2 ... > output.ps
  505. without specifying linemode explicitly, the successive datasets read
  506. from the files on the command line will appear in linemode #1, linemode
  507. #2, ....  If you do not like this feature, you may turn it off, or in
  508. general toggle it, by using the `-B' option.
  509.    You may also control manually the linemode and symbol type used for
  510. the datasets within any file.  You would do this by including
  511. directives in the file itself, rather than on the command line.  For
  512. example, if the line
  513.      #m=-5,S=10
  514. appeared in an ASCII-format input file, it would be interpreted as a
  515. directive to switch to linemode #-5 and symbol type #10 for the
  516. following dataset.  Future releases of `graph' may provide the ability
  517. to set each of the seven dataset attributes in this way.
  518. File: plotutils.info,  Node: Multiplotting,  Next: Data Formats,  Prev: Multiple Datasets,  Up: graph
  519. Multiplotting: placing multiple plots on a single page
  520. ======================================================
  521.    It is occasionally useful to display several plots at once on a
  522. single page, or on a single graphics display.  We call such a composite
  523. plot a *multiplot*.  One common sort of multiplot is a small plot inset
  524. into a larger one.  Another sort is two or more plots side by side.
  525.    `graph' can draw multiplots consisting of an arbitrarily large
  526. number of sub-plots.  When multiplotting, `graph' draws each sub-plot
  527. in its own `virtual display'.  When an ordinary plot is drawn, the
  528. virtual display is the same as the physical display.  But when a
  529. multiplot is drawn, the virtual display may be any smaller square
  530. region.  The following example illustrates the idea.
  531.      graph -T ps data_file_1 --reposition .35 .35 .3 data_file_2
  532. Here `data_file_1' is plotted in the usual way.  The `--reposition'
  533. option specifies that when `data_file_2' is plotted, it will be drawn
  534. within a virtual display.  For the purposes of the `--reposition'
  535. option, the physical display is a square with lower left corner
  536. (0.0,0.0) and upper right corner (1.0,1.0).  In those coordinates, the
  537. virtual display will be a square of size 0.3 with lower left corner
  538. (0.35,0.35).  So the second sub-plot will be inset into the first.
  539.    Just as the `-w', `-h', `-r', and `-u' options may be used to set
  540. the size and position of a plotting box within the physical display, so
  541. they may be used to set the size and position of a plotting box within
  542. a virtual display.  For example,
  543.      graph -T ps data_file_1 --reposition .35 .35 .3 -w .4 -r .3 data_file_2
  544. will yield a multiplot in which the second sub-plot is significantly
  545. different.  Its plotting box will have a width only 0.4 times the width
  546. of the virtual display.  However, the plotting box will be centered
  547. within the virtual display, since the distance between the left edge of
  548. the plotting box and the left edge of the virtual display will be 0.3
  549. times the width of the virtual display.
  550.    By convention, before each sub-plot of a multiplot other than the
  551. first is drawn, a `blankout region' surrounding its plotting box is
  552. erased.  (That is, it is filled with white.)  This erasure prevents the
  553. sub-plots from overlapping and producing a messy result.  By default,
  554. the blankout region is a rectangular region 30% larger in each dimension
  555. than the plotting box for the sub-plot.  This is appropriate if the
  556. sub-plot is a small one that is inset into the first sub-plot.  It may
  557. not be appropriate, however, if you are preparing a multiplot in which
  558. several sub-plots appear side by side.  You may use the `--blankout'
  559. option to adjust this parameter.  For example, specifying `--blankout
  560. 1.0' will make the blankout region for a sub-plot coincide with its
  561. plotting box.  Specifying `--blankout 0.0' will prevent any blanking
  562. out from occurring.  The blankout parameter may differ from sub-plot to
  563. sub-plot.
  564.    It should be emphasized that every sub-plot in a multiplot is a plot
  565. in its own right.  All the usual options (`-m', `-S', `-x', `-y', etc.)
  566. can be applied to each sub-plot separately.  The options for a sub-plot
  567. should occur on the `graph' command line immediately after the
  568. `--reposition' option that applies to it.  Each sub-plot may be
  569. prepared from more than a single dataset, also.  The names of the data
  570. files for each subplot should occur on the command line before the
  571. following `--reposition' option, if any.
  572. File: plotutils.info,  Node: Data Formats,  Next: graph Invocation,  Prev: Multiplotting,  Up: graph
  573. Reading binary and other data formats
  574. =====================================
  575.    By default, `graph' reads datasets in ASCII format.  But it can also
  576. read datasets in any of three binary formats (single precision floating
  577. point, double precision floating point, and integer).  These three
  578. input formats are specified by the `-I d', `-I f', and `-I i' options,
  579. respectively.
  580.    There are two advantages to using binary data: 1) `graph' runs
  581. significantly faster because the computational overhead for converting
  582. data from ASCII to binary is eliminated, and 2) the input files may be
  583. significantly smaller.  If you have very large datasets, using binary
  584. format may reduce storage and runtime costs.
  585.    For example, you may create a single precision binary dataset as
  586. output from a C language program:
  587.      #include <stdio.h>
  588.      void write_point (float x, float y)
  589.      {
  590.        fwrite(&x, sizeof (float), 1, stdout);
  591.        fwrite(&y, sizeof (float), 1, stdout);
  592.      }
  593. You may plot data written this way by doing:
  594.      graph -T ps -I f < binary_data_file > plot.ps
  595. The inclusion of multiple datasets within a single binary file is
  596. supported.  If a binary file contains more than a single dataset,
  597. successive datasets should be separated by a single occurrence of the
  598. the largest possible number.  For single precision datasets this is the
  599. quantity `FLT_MAX', for double precision datasets it is the quantity
  600. `DBL_MAX', and for integer datasets it is the quantity `INT_MAX'.  On
  601. most machines `FLT_MAX' is approximately 3.4x10^38, `DBL_MAX' is
  602. approximately 1.8x10^308, and `INT_MAX' is 2^32-1.
  603.    If you are reading datasets from more than one file, it is not
  604. required that the files be in the same format.  For example,
  605.      graph -T ps -I f binary_data_file -I a ascii_data_file > plot.ps
  606. will read `binary_data_file' in `f' (binary single precision) format,
  607. and `ascii_data_file' in `a' (normal ASCII) format.
  608.    There is currently no support for reading and plotting binary data
  609. with error bars.  If you have data with error bars, you should supply
  610. the data to `graph' in ASCII, and use the `-I e' option.
  611.    `graph' can also read data files in the ASCII `table' format
  612. produced by the `gnuplot' plotting program.  For this, you should use
  613. the `-I g' option.  Such a data file may consist of more than one
  614. dataset.
  615.    To sum up: there are six supported data formats, `a' (normal ASCII),
  616. `e' (ASCII with error bars), `g' (the ASCII `table' format produced by
  617. `gnuplot'), `f' (binary single precision), `d' (binary double
  618. precision), and `i' (binary integer).  Input files may be in any of
  619. these six formats.
  620. File: plotutils.info,  Node: graph Invocation,  Prev: Data Formats,  Up: graph
  621. `graph' command-line options
  622. ============================
  623.    The `graph' program reads one or more datasets from files named on
  624. the command line or from standard input, and prepares a plot.  The
  625. display type or output format is specified with the `-T' option.  There
  626. are many command-line options for adjusting the visual appearance of
  627. the plot.
  628.    By default, `graph' reads ASCII data from the files specified on the
  629. command line.  The data are pairs of numbers, interpreted as the x
  630. and y coordinates of data points.  If no file names are specified, or
  631. the file name `-' is specified, the standard input is read.
  632.    The relative order of file names and command-line options is
  633. important.  Only the options that precede a file name on the command
  634. line take effect for that file.
  635.    The following sections list the possible command-line options.  Each
  636. option that takes an argument is followed, in parentheses, by the type
  637. and default value of the argument.  There are five sorts of option.
  638.    The behavior of `graph' is also affected by a number of environment
  639. variables, so there is a section discussing them as well.
  640. * Menu:
  641. * Plot Options::        Options affecting an entire plot
  642. * Dataset Options::     Options affecting the reading and plotting of datasets
  643. * Multiplot Options::   Options for drawing several plots at once
  644. * Raw graph Options::   Options relevant only to raw graph
  645. * Info Options::        Options requesting information (e.g., --help)
  646. * graph Environment::   Environment variables
  647. File: plotutils.info,  Node: Plot Options,  Next: Dataset Options,  Prev: graph Invocation,  Up: graph Invocation
  648. Plot options
  649. ------------
  650.    The following options affect an entire plot.  They should normally
  651. occur at most once, and should appear on the command line before the
  652. first file name.  If a multiplot is being drawn, they may (with the
  653. exception of the `-T' option) occur more than once.  If so, the second
  654. and later occurrences should be placed on the command line immediately
  655. after each `--reposition X Y' option.
  656. `-T TYPE'
  657. `--display-type TYPE'
  658.      (String, default "meta".)  Select a display type or output format
  659.      of TYPE, which may be one of the strings "X", "ps", "fig", "hpgl",
  660.      "tek", and "meta".  These refer respectively to the
  661.      X Window System, `idraw'-editable Postscript, the format used by
  662.      the `xfig' drawing editor, the Hewlett-Packard Graphics Language,
  663.      Tektronix format, and device-independent GNU metafile format.
  664. `-f FONT_SIZE'
  665. `--font-size FONT_SIZE'
  666.      (Float, default 0.0525.)  Set the size of the font used for the
  667.      axis and tick labels, as a fraction of the size of the `plotting
  668.      box' (the box that frames the plot), to be FONT_SIZE.
  669. `-F FONT_NAME'
  670. `--font-name FONT_NAME'
  671.      (String, default "Helvetica" except for `graph -T hpgl' and `graph
  672.      -T tek', for which "HersheySerif" is the default.)  Set the font
  673.      used for the axis and tick labels, and for the plot title
  674.      (if any), to be FONT_NAME.  The choice of font for the plot title
  675.      may be overridden with the `--title-font-name' option (see below).
  676.      Font names are case-insensitive.  If the specified font is not
  677.      available, the default font will be used.  Which fonts are
  678.      available depends on which `-T' option is used.  For a list of all
  679.      fonts, see *Note Text Fonts::.  The `plotfont' utility will
  680.      produce a character map of any available font.  *Note plotfont::.
  681. `-g GRID_STYLE'
  682. `--grid-style GRID_STYLE'
  683.      (Integer in the range 0...4, default 2.)  Set the grid style for
  684.      the plot to be GRID_STYLE.  Grid styles 0 through 3 are
  685.      progressively more fancy, but style 4 is a somewhat different
  686.      style.
  687.        0. no axes, tick marks or labels.
  688.        1. a pair of axes, with tick marks and labels.
  689.        2. box around plot, with tick marks and labels.
  690.        3. box around plot, with tick marks and labels; also grid lines.
  691.        4. axes intersect at the origin, with tick marks and labels.
  692. `-h HEIGHT'
  693. `--height-of-plot HEIGHT'
  694.      (Float, default 0.6.)  Set the fractional height of the plot with
  695.      respect to the height of the display (or virtual display, in the
  696.      case of a multiplot) to be HEIGHT.  A value of 1.0 will produce a
  697.      plotting box that fills the available area.  Note that tick marks
  698.      and labels are outside the plotting box, so that values less than
  699.      1.0 are generally used.
  700. `-K CLIP_MODE'
  701. `--clip-mode CLIP_MODE'
  702.      (Integer, default 1.) Set the clip mode for the plot to CLIP_MODE.
  703.      The clip mode is relevant only if data points are being joined by a
  704.      line, and the line is not being filled to create a filled region
  705.      (since filled regions are clipped in a fixed way).  There are
  706.      three clip modes: 0, 1, and 2.  Clip mode 0 means that a line
  707.      segment joining two data points will be plotted only if neither
  708.      point is outside the plotting box.  Clip mode 1 means that it will
  709.      be plotted if no more than one of the two points is outside, and
  710.      clip mode 2 means that it will be plotted even if both are
  711.      outside.  In all cases the line segment will be clipped to the
  712.      plotting box.
  713. `-L TOP_LABEL'
  714. `--top-label TOP_LABEL'
  715.      (String, default empty.)  Place the text string TOP_LABEL above
  716.      the plot, as a plot title.  The string may include escape sequences
  717.      (*note Text String Format::.).  The `--title-font-size' option may
  718.      be used to specify the size of the font.  The font is normally the
  719.      same as the font used for labelling axes and tick labels, as
  720.      selected by the `-F' option.  But this can be overridden with the
  721.      `--title-font-name' option.
  722. `-l X|Y'
  723. `--toggle-log-axis X|Y'
  724.      Set the specified axis to be a log axis rather than a linear axis,
  725.      or vice versa.  By default, both axes are linear axes.
  726. `-N X|Y'
  727. `--toggle-no-ticks X|Y'
  728.      Toggle the presence of ticks and tick labels on the specified axis.
  729.      This applies to the grid styles that normally include ticks and
  730.      tick labels, i.e., grid styles 1, 2, 3, and 4.
  731. `-R X|Y'
  732. `--toggle-round-to-next-tick X|Y'
  733.      Toggle the rounding of the limits of the specified axis, so that
  734.      they are integer multiples of the spacing between labeled tick
  735.      marks.  By default this does not take place if the user uses the
  736.      `-x' or `-y' options to set axis limits explicitly.
  737. `-r RIGHT'
  738. `--right-shift RIGHT'
  739.      (Float, default 0.2.)  Move the plot to the right by a fractional
  740.      amount RIGHT with respect to the width of the display (or virtual
  741.      display, in the case of a multiplot).  This produces a margin on
  742.      the left side of the plotting box.  A value of 0.5 will produce a
  743.      margin half the width of the available area.  Note that the tick
  744.      marks and labels are drawn in the margin.
  745. `--save-screen'
  746.      Save the screen.  This option requests that `graph' not erase the
  747.      display device before it begins to plot.  This is relevant only to
  748.      `graph -T tek'.  It may be employed to perform a crude sort of
  749.      multiplotting, since Tektronix displays and emulators are
  750.      persistent, in the sense that previously drawn graphics remain
  751.      visible.
  752. `-T TICK_SIZE'
  753. `--tick-size TICK_SIZE'
  754.      (Float, default .02.) Set the fractional size of the tick marks on
  755.      each axis to be TICK_SIZE.  A value of 1.0 produces tick marks on
  756.      the x axis whose length is equal to the width of the plotting box.
  757.      A negative TICK_SIZE will yield tick marks that extend outside
  758.      the box, rather than inside.
  759. `--toggle-transpose-axes'
  760.      Transpose the abscissa and ordinate.  This causes the axes to be
  761.      interchanged, and the options that apply to each axis to be
  762.      applied to the opposite axis.  That is, data points are read in as
  763.      (y, x) pairs, and such options as `-x' and `-X' apply to the
  764.      y axis rather than the x axis.  If the `-I e' option is in force,
  765.      so that the data points are read with error bars, the orientation
  766.      of the error bars will be switched between vertical and horizontal.
  767. `-u UP'
  768. `--upward-shift UP'
  769.      (Float, default 0.2.)  Move the plot up by a fractional amount UP
  770.      with respect to the height of the display (or virtual display, in
  771.      the case of a multiplot).  This produces a margin below the
  772.      plotting box.  A value of 0.5 will produce a margin half the
  773.      height of the available area.  Note that the tick marks and labels
  774.      are drawn in the margin.
  775. `-w WIDTH'
  776. `--width-of-plot WIDTH'
  777.      (Float, default 0.6.) Set the fractional width of the plot with
  778.      respect to the width of the display (or virtual display, in the
  779.      case of a multiplot) to be WIDTH.  A value of 1.0 will produce a
  780.      plotting box that fills the available area.  Note that the tick
  781.      marks and labels are outside the plotting box, so values less than
  782.      1.0 are generally used.
  783. `-x [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]'
  784. `--x-limits [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]'
  785.      (Floats.) The arguments LOWER_LIMIT and UPPER_LIMIT specify the
  786.      limits of the x axis, and the optional argument SPACING specifies
  787.      the spacing of labeled ticks along the axis.  If any of the three
  788.      arguments is missing, it is computed from the data.  The arguments
  789.      LOWER_LIMIT and UPPER_LIMIT must be present if `graph' is to act
  790.      as a real-time filter.
  791. `-y [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]'
  792. `--y-limits [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]'
  793.      (Floats.)  The arguments specify the limits of the y axis, and the
  794.      spacing of labeled ticks along it, as for the x axis (see above).
  795.      The arguments LOWER_LIMIT and UPPER_LIMIT must be present if
  796.      `graph' is to act as a real-time filter.
  797. `-X X_LABEL'
  798. `--x-title X_LABEL'
  799.      (String, default empty.)  Set the label for the x axis to be the
  800.      text string X_LABEL.  The string may include escape sequences
  801.      (*note Text String Format::.).  The `-F' and `-f' options may be
  802.      used to specify the name of the font and the size of the font.
  803. `-Y Y_LABEL'
  804. `--y-title Y_LABEL'
  805.      (String, default empty.) Set the label for the y axis to be the
  806.      text string Y_LABEL.  The string may include escape sequences
  807.      (*note Text String Format::.).  The label will be rotated by 90
  808.      degrees so that it is parallel to the axis, unless the
  809.      `--toggle-rotate-y-label' option is used.  Some old X Window System
  810.      displays do not support rotated labels, and require the
  811.      `--toggle-rotate-y-label' option.  The `-F' and `-f' options can
  812.      be used to specify the name of the font and the size of the font.
  813. `--bg-color NAME'
  814.      (String, default "white".)  Set the color used for the plot
  815.      background to be NAME.  This is currently relevant only to `graph
  816.      -T X'.  An unrecognized name sets the color to the default.  For
  817.      information on what names are recognized, see *Note Color Names::.
  818.      The environment variable `BG_COLOR' can equally well be used to
  819.      specify the background color.
  820. `--bitmap-size BITMAP_SIZE'
  821.      (String, default "570x570".)  Set the size of the graphics display
  822.      in which the plot will be drawn, in terms of pixels, to be
  823.      BITMAP_SIZE.  This is relevant only to `graph -T X', for which the
  824.      graphics display is an X window.  If you choose a rectangular
  825.      (non-square) window size, the fonts in the plot will be scaled
  826.      anisotropically, i.e., by different factors in the horizontal and
  827.      vertical direction.  This requires an X11R6 display.  Any font that
  828.      cannot be scaled in this way will be replaced by a default scalable
  829.      font, such as the Hershey vector font "HersheySerif".
  830.      The environment variable `BITMAPSIZE' can equally well be used to
  831.      specify the window size.  For backward compatibility, the
  832.      X resource `Xplot.geometry', which can be set by the user, may be
  833.      used instead.
  834. `--frame-color NAME'
  835.      (String, default "black".)  Set the color used for drawing the plot
  836.      frame, and for drawing monochrome datasets (if any) to be NAME.
  837.      An unrecognized name sets the color to the default.  For
  838.      information on what names are recognized, see *Note Color Names::.
  839. `--frame-line-width FRAME_LINE_WIDTH'
  840.      (Float, default -1.0.)  Set the width of lines in the plot frame,
  841.      as a fraction of the width of the display, to FRAME_LINE_WIDTH.
  842.      A negative value means that the default value for the line width
  843.      provided by the `libplot' graphics library should be used.  This
  844.      value is device-dependent.  The interpretation of zero line width
  845.      is also device-dependent (on some devices, a zero-width line is the
  846.      thinnest line that can be drawn; on others, a zero-width line is
  847.      invisible).
  848.      `graph -T tek' does not support drawing lines with other than a
  849.      default width, and `graph -T hpgl' does not support doing so if
  850.      the environment variable `HPGL_VERSION' is set to a value less
  851.      than "2" (the default).
  852. `--max-line-length MAX_LINE_LENGTH'
  853.      (Integer, default 500.) Set the maximum number of points that a
  854.      polygonal line drawn through any dataset may contain, before it is
  855.      flushed to the display device, to equal MAX_LINE_LENGTH.  If this
  856.      flushing occurs, the polygonal line will be split into two or more
  857.      sub-lines, though the splitting should not be noticeable.
  858.      Splitting will not take place if the `-q' option, which requests
  859.      filling, is used.
  860.      The reason for splitting long polygonal lines is that some display
  861.      devices (e.g., old Postscript printers and HP-GL plotters) have
  862.      limited buffer sizes.  The environment variable `MAX_LINE_LENGTH'
  863.      can also be used to specify the maximum line length.  This option
  864.      has no effect on `graph -T tek' or raw `graph', since they draw
  865.      polylines in real time and have no buffer limitations.
  866. `--page-size PAGESIZE'
  867.      (String, default "letter".)  Set the size of the page on which the
  868.      plot will be positioned.  This is relevant only to `graph -T ps',
  869.      `graph -T fig', and `graph -T hpgl'.  "letter" means an 8.5in by
  870.      11in page.  Any ISO page size in the range "a0"..."a4" or ANSI
  871.      page size in the range "a"..."e" may be specified ("letter" is an
  872.      alias for "a" and "tabloid" is an alias for "b").  "legal" and
  873.      "ledger" are recognized page sizes also.  The environment variable
  874.      `PAGESIZE' can equally well be used to specify the page size.
  875.      For `graph -T ps', the graphics display within which the plot is
  876.      drawn will be a square region centered on the specified page and
  877.      occupying its full width.  For `graph -T fig', the graphics
  878.      display will be a square region located in the upper left corner
  879.      of an `xfig' display, with width equal to the width of the
  880.      specified page.  `graph -T hpgl', fine control over the
  881.      positioning of the graphics display on the page can be
  882.      accomplished by setting certain environment variables (*note graph
  883.      Environment::.).
  884. `--pen-colors COLORS'
  885.      (String, default "1=red:2=green:3=blue:4=magenta:5=cyan".)  Set the
  886.      colors of the pens used for drawing plots, as numbered, to be
  887.      COLORS.  The format should be self-explanatory.  An unrecognized
  888.      name sets the corresponding color to the default.  For information
  889.      on what names are recognized, see *Note Color Names::.
  890. `--title-font-name FONT_NAME'
  891.      (String, default "Helvetica" except for `graph -T hpgl' and `graph
  892.      -T tek', for which "HersheySerif" is the default.)  Set the font
  893.      used for the plot title (`top label') to be FONT_NAME.  Normally
  894.      the font used for the plot title is the same as that used for
  895.      labelling the axes and the ticks along the axes, as specified by
  896.      the `-F' option.  But the `--title-font-name' option can be used
  897.      to override this.  Font names are case-insensitive.  If the
  898.      specified font is not available, the default font will be used.
  899.      Which fonts are available depends on which `-T' option is used.
  900.      For a list of all fonts, see *Note Text Fonts::.  The `plotfont'
  901.      utility will produce a character map of any available font.  *Note
  902.      plotfont::.
  903. `--title-font-size FONT_SIZE'
  904.      (Float, default 0.07.)  Set the size of the font for the top label
  905.      (`title'), as specified by the `-L' option, to FONT_SIZE.  The
  906.      size is expressed as a fraction of the size of the plotting box.
  907. `--toggle-rotate-y-label'
  908.      Position the label on the y axis (which is set with the `-Y'
  909.      option) horizontally instead of vertically, or vice versa.  By
  910.      default the label is rotated, so that it is positioned parallel to
  911.      the y axis.  But some display devices (e.g., old X Window System
  912.      displays) cannot handle rotated fonts.
  913. `--toggle-switch-axis-end X|Y'
  914.      Set the end of the indicated axis through which the other axis
  915.      passes to be the opposite of what is currently the case.  E.g.,
  916.      `--toggle-switch-axis-end x' will cause the y axis to appear on
  917.      the right of the plot rather than the left.  (The left end is the
  918.      default.)  Similarly, `--toggle-switch-axis-end y' will cause the
  919.      x axis to appear at the top of the plot rather than the bottom.
  920.      Note that if the x axis appears at the top, no plot title will be
  921.      drawn (since there will be no room).
  922. File: plotutils.info,  Node: Dataset Options,  Next: Multiplot Options,  Prev: Plot Options,  Up: graph Invocation
  923. Dataset options
  924. ---------------
  925.    The following options affect the way in which individual datasets are
  926. read from files, and drawn as part of a plot.  They should appear on the
  927. command line before the file containing the datasets whose reading or
  928. rendering they will affect.  They may appear more than once on a command
  929. line, if more than one file is to be read.
  930.    The following three options affect the way in which datasets are read
  931. from files.
  932. `-I DATA-FORMAT'
  933. `--input-format DATA-FORMAT'
  934.      This specifies which format the subsequent input file(s) are in.
  935.     `a'
  936.           ASCII format.  Each input file is a sequence of floating
  937.           point numbers, interpreted as the x and y coordinates of the
  938.           successive data points in a dataset.  The x and y coordinates
  939.           of a point need not appear on the same line, and points need
  940.           not appear on different lines.  But if a blank line occurs
  941.           (i.e., two newlines in succession are seen), it is
  942.           interpreted as the end of a dataset, and the beginning of the
  943.           next.
  944.     `e'
  945.           ASCII format, including error bars.  Similar to `a' format,
  946.           except that triples (x,y,error) appear instead of pairs (x,y).
  947.     `g'
  948.           The ASCII `table' format produced by the `gnuplot' plotting
  949.           program.
  950.     `f'
  951.           Single precision binary format.  Each input file is a
  952.           sequence of single precision floating point numbers,
  953.           interpreted as forming pairs (x,y).  Successive datasets are
  954.           separated by a single occurrence of the quantity `FLT_MAX',
  955.           which is the largest possible single precision floating point
  956.           number.  On most machines this is approximately 3.4x10^38.
  957.     `d'
  958.           Double precision binary format.  Each input file is a
  959.           sequence of double precision floating point numbers,
  960.           interpreted as forming pairs (x,y).  Successive datasets are
  961.           separated by a single occurrence of the quantity `DBL_MAX',
  962.           which is the largest possible double precision floating point
  963.           number.  On most machines this is approximately 1.8x10^308.
  964.     `i'
  965.           Integer binary format.  Each input file is a sequence of
  966.           integers, interpreted as forming pairs (x,y).  Successive
  967.           datasets are separated by a single occurrence of the quantity
  968.           `INT_MAX', which is the largest possible integer.  On most
  969.           machines this is 2^31-1.
  970. `-a [STEP_SIZE [LOWER_LIMIT]]'
  971. `--auto-abscissa [STEP_SIZE [LOWER_LIMIT]]'
  972.      (Floats, defaults 1.0 and 0.0.) Automatically generate abscissa
  973.      (x) values.  Irrespective of data format (`a', `e', `f', `d',
  974.      or `i'), this option specifies that the abscissa (x) values are
  975.      missing from the input file: the dataset(s) to be read contain
  976.      only ordinate (y) values.  The increment from each x value to the
  977.      next will be STEP_SIZE, and the first x value will be LOWER_LIMIT.
  978.      To return to reading abscissa values from the input, i.e., for
  979.      subsequent input files, you would use `-a 0', which disables
  980.      automatic generation of the abscissa values and returns STEP_SIZE
  981.      and LOWER_LIMIT to their default values.
  982. `--toggle-auto-bump'
  983.      By default the linemode (set with `-m', see below) is `bumped'
  984.      (incremented by unity) at the beginning of each new dataset.  This
  985.      option toggles auto-bumping: it turns it off if it was on, and on
  986.      if it was off.
  987.    The following options affect the way in which individual datasets are
  988. drawn as part of a plot.  These options set the six `attributes' (symbol
  989. type, symbol font, linemode, line width, fill fraction, and
  990. color/monochrome) that each dataset has.
  991. `-m LINE_MODE'
  992. `--line-mode LINE_MODE'
  993.      (Integer, default 1.) LINE_MODE specifies the mode (i.e., style)
  994.      of the lines drawn between successive points in a dataset.  By
  995.      convention, linemode #0 means no line at all (points are
  996.      disconnected).  If the dataset is being rendered in monochrome, the
  997.      interpretation of LINE_MODE is as follows.
  998.        1. solid
  999.        2. dotted
  1000.        3. dotdashed
  1001.        4. shortdashed
  1002.        5. longdashed
  1003.      Thereafter (i.e., for LINE_MODE greater than 5) the sequence of
  1004.      five linemodes repeats.  So besides linemode #0, there are a total
  1005.      of five distinct monochrome linemodes.  If the dataset is being
  1006.      rendered in color (as may be requested with the `-C' option), the
  1007.      interpretation of linemodes #1 through #5 is instead
  1008.        1. red, solid
  1009.        2. green, solid
  1010.        3. blue, solid
  1011.        4. magenta, solid
  1012.        5. cyan, solid
  1013.      Linemodes #6 through #10 use the same five colors, but are dotted;
  1014.      linemodes #11 through #15 are dotdashed; linemodes #16 through #20
  1015.      are shortdashed; and linemodes #21 through #25 are longdashed.  So
  1016.      besides linemode #0, there are a total of 25 distinct colored
  1017.      linemodes.  A negative linemode indicates that no line should be
  1018.      drawn, but that the plotting symbol, if any (see below), should be
  1019.      in the color of the corresponding positive linemode.
  1020. `-S [SYMBOL_NUMBER [SYMBOL_SIZE]]'
  1021. `--symbol [SYMBOL_NUMBER [SYMBOL_SIZE]]'
  1022.      (Integer and float, defaults 0 and 0.03.) Draw a marker symbol at
  1023.      each data point.  SYMBOL_NUMBER specifies the symbol type, and
  1024.      SYMBOL_SIZE specifies the fractional size of the symbol with
  1025.      respect to the width of the plotting box.  If the dataset is being
  1026.      rendered in color, the symbol will have the color of the line that
  1027.      is being drawn to connect the data points.  You may request that
  1028.      symbols be drawn without any line connecting them by using the
  1029.      `-m' option to specify a negative linemode (see above).  The
  1030.      following table lists the first few marker symbols (by convention,
  1031.      symbol #0 means no symbol at all).
  1032.        1. dot
  1033.        2. plus (+)
  1034.        3. asterisk (*)
  1035.        4. circle
  1036.        5. cross
  1037.      Marker symbols 0 through 31 are furnished by the `libplot' graphics
  1038.      library.  *Note Marker Symbols::.  Symbol numbers greater than or
  1039.      equal to 32 are interpreted as characters to be selected from a
  1040.      symbol font, which can be set with the `--symbol-font-name' option
  1041.      (see below).
  1042. `-W LINE_WIDTH'
  1043. `--line-width LINE_WIDTH'
  1044.      (Float, default -1.0.)  Set the width of the lines used to join
  1045.      successive points in a dataset, as a fraction of the width of the
  1046.      display, to LINE_WIDTH.  A negative value means that the default
  1047.      value for the line width provided by the `libplot' graphics
  1048.      library should be used.  This value is device-dependent.  The
  1049.      interpretation of zero line width is also device-dependent (on some
  1050.      devices, a zero-width line is the thinnest line that can be drawn;
  1051.      on others, a zero-width line is invisible).
  1052.      `graph -T tek' does not support drawing lines with other than a
  1053.      default width, and `graph -T hpgl' does not support doing so if
  1054.      the environment variable `HPGL_VERSION' is set to a value less
  1055.      than "2" (the default).
  1056. `-q FILL_FRACTION'
  1057. `--fill-fraction FILL_FRACTION'
  1058.      (Float, default -1.0.)  If successive points in a dataset are
  1059.      joined by line segments, set the shading intensity for the polygon
  1060.      formed by the line segments to be FILL_FRACTION.  A solid polygon
  1061.      (i.e., one filled with the `pen color' used for drawing the line
  1062.      segments) is obtained by choosing FILL_FRACTION=1.0.  The interior
  1063.      of the polygon will be white if FILL_FRACTION=0.0.  The polygon
  1064.      will be unfilled (transparent) if FILL_FRACTION is negative.
  1065.      If the polygon intersects itself, the `even-odd rule' will be used
  1066.      to determine which points are inside and outside, i.e., to
  1067.      determine which portions of the polygon should be shaded.  The
  1068.      even-odd rule is explained in the `Postscript Language Reference
  1069.      Manual'.  The `-q' option has no effect in `graph -T tek', and it
  1070.      is only partly effective in `graph -T hpgl' if the environment
  1071.      variable `HPGL_VERSION' is set to "1".
  1072. `--toggle-use-color'
  1073.      Toggle between color and monochrome rendering of datasets.  The
  1074.      interpretation of linemode depends on whether the rendering is
  1075.      being performed in color or monochrome; see the `-m' option above.
  1076. `--symbol-font-name SYMBOL_FONT_NAME'
  1077.      (String, default "ZapfDingbats" unless `-T hpgl' or `-T tek' is
  1078.      specified, in which case it is "HersheySerif".)  Set the symbol
  1079.      font, from which plotting symbols numbered 32 and higher are
  1080.      selected, to be SYMBOL_FONT_NAME.  Font names are
  1081.      case-insensitive.  If the specified font is not available, the
  1082.      default font will be used.  Which fonts are available depends on
  1083.      which `-T' option is used.  For example, if the `-T hpgl' is used
  1084.      then normally the Wingdings font, which is an alternative source
  1085.      of symbols, becomes available.  For a list of all fonts, see *Note
  1086.      Text Fonts::.  The `plotfont' utility will produce a character map
  1087.      of any available font.  *Note plotfont::.
  1088. File: plotutils.info,  Node: Multiplot Options,  Next: Raw graph Options,  Prev: Dataset Options,  Up: graph Invocation
  1089. Multiplot options
  1090. -----------------
  1091.    The following options are used for multiplotting (placing several
  1092. plots on a display, or a page, at once).
  1093. `--reposition X Y SIZE'
  1094.      (Floats, defaults 0.0, 0.0, 1.0) Set the `virtual display' within
  1095.      which the next plot will be drawn to be a square of size SIZE, with
  1096.      lower left corner (X,Y).  Normalized coordinates are used here:
  1097.      (0,0) means the lower left corner of the physical display and
  1098.      (1,1) means the upper right corner of the physical display.  The
  1099.      size of the plot within the virtual display may be adjusted with
  1100.      the `-h' and `-w' options, and its position within the virtual
  1101.      display with the `-u' and `-w' options.  After a `--reposition'
  1102.      command, the arguments of those four options will be interpreted in
  1103.      terms of the virtual display, not the physical display.
  1104. `--blankout BLANKOUT_FRACTION'
  1105.      (Float, default 1.3.)  When drawing each additional plot of a
  1106.      multiplot, it is desirable to clear the region of the display on
  1107.      which the plot will be drawn.  If BLANKOUT_FRACTION=1.0, the
  1108.      region covered by the plot's plotting box will be cleared.  If
  1109.      BLANKOUT_FRACTION=1.3, a region 30% larger in each dimension will
  1110.      be cleared.  This is appropriate for inset plots; 1.0 would be
  1111.      appropriate for side by side plots.  Note that `graph -T tek'
  1112.      cannot clear regions, and `graph -T hpgl' cannot clear them if the
  1113.      environment variables `HPGL_VERSION' and `HPGL_OPAQUE_MODE' are
  1114.      set to non-default values (i.e., values other than "2" and "yes",
  1115.      respectively).
  1116. File: plotutils.info,  Node: Raw graph Options,  Next: Info Options,  Prev: Multiplot Options,  Up: graph Invocation
  1117. Raw `graph' options
  1118. -------------------
  1119.    The following option is relevant only to raw `graph', i.e., is
  1120. relevant only if no display type or output format is specified with the
  1121. `-T' option.  In this case `graph' outputs a graphics metafile, which
  1122. may be translated to other formats by invoking `plot'.  This option
  1123. should appear on the command line before any file names, since it
  1124. affects the output of the plot (or multiplot) as a whole.
  1125. `--portable-output'
  1126.      Output the portable (human-readable) version of GNU metafile
  1127.      format, rather than a binary version (the default).
  1128. File: plotutils.info,  Node: Info Options,  Next: graph Environment,  Prev: Raw graph Options,  Up: graph Invocation
  1129. Informational options
  1130. ---------------------
  1131.    The following options request information.
  1132. `--help'
  1133.      Print a list of command-line options, and then exit.
  1134. `--help-fonts'
  1135.      Print a table of available fonts, and then exit.  The table will
  1136.      depend on which display type or output format is specified with
  1137.      the `-T' option.  `graph -T X', `graph -T ps', and `graph -T fig'
  1138.      each support the 35 standard Postscript fonts.  `graph -T hpgl'
  1139.      supports the 45 standard PCL 5 fonts.  All four, together with
  1140.      `graph -T tek', support a set of 22 Hershey vector fonts.  Raw
  1141.      `graph' in principle supports any of these 102 fonts, since its
  1142.      output must be translated to other formats with `plot'.  The
  1143.      `plotfont' utility will produce a character map of any available
  1144.      font.  *Note plotfont::.
  1145. `--list-fonts'
  1146.      Like `--help-fonts', but lists the fonts in a single column to
  1147.      facilitate piping to other programs.  If no display type or output
  1148.      format is specified with the `-T' option, the full set of supported
  1149.      fonts is listed.
  1150. `--version'
  1151.      Print the version number of `graph' and the plotting utilities
  1152.      package, and exit.
  1153. File: plotutils.info,  Node: graph Environment,  Prev: Info Options,  Up: graph Invocation
  1154. Environment variables
  1155. =====================
  1156.    The behavior of `graph' is affected by several environment
  1157. variables.  We have already mentioned the environment variables
  1158. `BITMAPSIZE', `PAGESIZE', `BG_COLOR', and `MAX_LINE_LENGTH'.  They
  1159. serve as backups for the options `--bitmap-size', `--page-size',
  1160. `--bg-color', and `--max-line-length'.  The remaining environment
  1161. variables are specific to individual display types.  They control
  1162. device driver parameters.
  1163.    `graph -T X', which pops up a window on an X Window System display
  1164. and draws graphics in it, checks the `DISPLAY' environment variable.
  1165. The value of this variable determines the display on which the window
  1166. will be popped up.
  1167.    `graph -T hpgl', which produces Hewlett-Packard Graphics Language
  1168. output, is affected by several environment variables.  The most
  1169. important is `HPGL_VERSION', which may be set to "1", "1.5", or "2"
  1170. (the default).  "1" means that the output should be generic HP-GL,
  1171. "1.5" means that the output should be suitable for the HP7550A graphics
  1172. plotter and the HP758x, HP7595A and HP7596A drafting plotters (HP-GL
  1173. with some HP-GL/2 extensions), and "2" means that the output should be
  1174. modern HP-GL/2.  If the version is "1" or "1.5" then the only available
  1175. fonts will be vector fonts, and all lines will be drawn with a default
  1176. width (the `-W' option will not work).  Additionally, if the version
  1177. is "1" then the filling of arbitrary curves with solid color will not
  1178. be supported (the `-q' option may be used to fill circles and
  1179. rectangles aligned with the coordinate axes, though).
  1180.    The position of the `graph -T hpgl' graphics display on the page can
  1181. be adjusted by setting the `HPGL_XOFFSET' and `HPGL_YOFFSET'
  1182. environment variables, which may be specified in centimeters,
  1183. millimeters, or inches.  For example, an offset could be specified as
  1184. "2cm" or "1.2in".  Also, the display can be rotated 90 degrees
  1185. counterclockwise on the page by setting the `HPGL_ROTATE' environment
  1186. variable to "yes".  Besides "no" and "yes", recognized values for this
  1187. variable are "0", "90", "180", and "270".  "no" and "yes" are
  1188. equivalent to "0" and "90", respectively.  "180" and "270" are
  1189. supported only if `HPGL_VERSION' is "2" (the default).
  1190.    *Opaque* filling and the drawing of visible white lines are
  1191. supported only if `HPGL_VERSION' is "2" and the environment variable
  1192. `HPGL_OPAQUE_MODE' is "yes" (the default).  If the value is "no" then
  1193. opaque filling will not be used, and white lines (if any), which are
  1194. normally drawn with pen #0, will not be drawn.  This feature is to
  1195. accommodate older HP-GL/2 devices.  HP-GL/2 pen plotters, for example,
  1196. do not support opacity or the use of pen #0 to draw visible white
  1197. lines.  Some older HP-GL/2 devices reportedly malfunction if asked to
  1198. draw opaque objects.
  1199.    By default, `graph -T hpgl' will draw with a fixed set of pens.
  1200. Which pens are present may be specified by setting the `HPGL_PENS'
  1201. environment variable.  If `HPGL_VERSION' is "1", the default value of
  1202. `HPGL_PENS' is "1=black"; if `HPGL_VERSION' is "1.5" or "2", the
  1203. default value of `HPGL_PENS' is
  1204. "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan".  The format
  1205. should be self-explanatory.  By setting `HPGL_PENS', you may specify a
  1206. color for any pen in the range #1...#31.  For information on what color
  1207. names are recognized, see *Note Color Names::.  Pen #1 must always be
  1208. present, though it need not be black. Any other pen in the range
  1209. #1...#31 may be omitted.
  1210.    If `HPGL_VERSION' is "2" then `graph -T hpgl' will also be affected
  1211. by the environment variable `HPGL_ASSIGN_COLORS'.  If the value of this
  1212. variable is "yes", then `graph -T hpgl' will not be restricted to the
  1213. palette specified in `HPGL_PENS': it will assign colors to "logical
  1214. pens" in the range #1...#31, as needed.  The default value is "no"
  1215. because other than color LaserJet printers and DesignJet plotters, not
  1216. many HP-GL/2 devices allow the assignment of colors to logical pens.
  1217.    `graph -T tek', which produces output for a Tektronix terminal or
  1218. emulator, checks the `TERM' environment variable.  If the value of
  1219. `TERM' is `xterm', `xterms', or `kterm', it is taken as a sign that the
  1220. current application is running in an X Window System VT100 terminal
  1221. emulator: an `xterm'.  Before drawing graphics, `graph -T tek' will
  1222. emit an escape sequence that causes the terminal emulator's auxiliary
  1223. Tektronix window, which is normally hidden, to pop up.  After the
  1224. graphics are drawn, an escape sequence that returns control to the
  1225. original VT100 window will be emitted.  The Tektronix window will
  1226. remain on the screen.
  1227.    If the value of `TERM' is `kermit', `ansi.sys', `ansissys',
  1228. `ansi.sysk', or `ansisysk', it is taken as a sign that the current
  1229. application is running in the VT100 terminal emulator provided by the
  1230. MS-DOS version of `kermit'.  Before drawing graphics, `graph -T tek'
  1231. will emit an escape sequence that switches the terminal emulator to
  1232. Tektronix mode.  Also, some of the Tektronix control codes emitted by
  1233. `graph -T tek' will be `kermit'-specific.  There will be a limited
  1234. amount of color support, which is not normally the case (the 16
  1235. `ansi.sys' colors will be supported).  After drawing graphics, `graph
  1236. -T tek' will emit an escape sequence that returns the emulator to VT100
  1237. mode.  The key sequence `ALT minus' can be employed manually within
  1238. `kermit' to switch between the two modes.
  1239. File: plotutils.info,  Node: plot,  Next: tek2plot,  Prev: graph,  Up: Top
  1240. The `plot' Program
  1241. ******************
  1242. * Menu:
  1243. * plot Examples::       How to use a plot filter
  1244. * plot Invocation::     Command-line options
  1245. * plot Environment::    Environment variables
  1246. File: plotutils.info,  Node: plot Examples,  Next: plot Invocation,  Prev: plot,  Up: plot
  1247. How to use `plot'
  1248. =================
  1249.    The GNU plot filter `plot' displays GNU graphics metafiles, or
  1250. translates them to other formats.  The `-T' option is used to specify
  1251. the display type or output format.
  1252.    Graphics metafiles are produced by the `graph' utility if no `-T'
  1253. option is specified on its command line, and can also be produced by
  1254. the `libplot' library.  The metafile format is a device-independent
  1255. format for storage of graphic data.  By default, it is a binary rather
  1256. than an human-readable format (*note Metafiles::.).
  1257.    `plot', like the metafile format itself, is useful if you wish to
  1258. preserve a plot that is to be displayed or edited on more than one type
  1259. of display.  The following illustrate how this is done.
  1260.    To produce a plot of data arranged as alternating x and y
  1261. coordinates in an ASCII file, you may use raw `graph' as follows:
  1262.      graph < ascii_data_file > test.plot
  1263. The file `test.plot' will be a GNU graphics metafile.  Similarly, to
  1264. create a plot consisting of a simple figure, you may do:
  1265.      echo 0 0 1 1 2 0 | spline | graph > test.plot
  1266. To display any such plot on an X Window System display, you would do
  1267.      plot -T X test.plot
  1268.      plot -T X < test.plot
  1269. To print the plot on a Postscript printer, you would do something like
  1270.      plot -T ps < test.plot | lpr
  1271. To edit it with the `idraw' drawing editor, you would do
  1272.      plot -T ps < test.plot > test.ps
  1273.      idraw test.ps
  1274. And to produce a plot that can be edited with the `xfig' drawing
  1275. editor, you would do
  1276.      plot -T fig < test.plot > test.fig
  1277.      xfig test.fig
  1278.    `plot' may behave differently depending on the environment in which
  1279. it is invoked.  In particular, `plot -T ps', `plot -T fig', and `plot
  1280. -T hpgl' are affected by the environment variable `PAGESIZE'.  `plot
  1281. -T X' is affected by the environment variables `DISPLAY' and
  1282. `BITMAPSIZE', and `plot -T tek' is affected by the environment variable
  1283. `TERM'.  There are also several environment variables that affect the
  1284. operation of `plot -T hpgl'.  For a complete discussion of the effects
  1285. of the environment on `plot', see *Note plot Environment::.
  1286. File: plotutils.info,  Node: plot Invocation,  Next: plot Environment,  Prev: plot Examples,  Up: plot
  1287. `plot' command-line options
  1288. ===========================
  1289.    The plot filter `plot' translates GNU graphics metafiles to other
  1290. formats.  The `-T' option is used to specify the display type or output
  1291. format.  Files in metafile format are produced by GNU `graph' and other
  1292. applications that use the GNU `libplot' graphics library.  For
  1293. technical details on the metafile format, see *Note Metafiles::.
  1294.    Input file names may be specified anywhere on the command line.  That
  1295. is, the relative order of file names and command-line options does not
  1296. matter.  If no file names are specified, or the file name `-' is
  1297. specified, the standard input is read.
  1298.    The full set of command-line options is listed below.  There are four
  1299. sorts of option:
  1300.   1. Options setting the values of drawing parameters.
  1301.   2. Options relevant only to raw `plot', i.e., relevant only if no
  1302.      display type or output format is specified with the `-T' option.
  1303.   3. Options specifying the type of metafile format the input is in (for
  1304.      backward compatibility only).
  1305.   4. Options requesting information (e.g., `--help').
  1306. Each option that takes an argument is followed, in parentheses, by the
  1307. type and default value of the argument.
  1308.    The following options set the values of drawing parameters.
  1309. `-T TYPE'
  1310. `--display-type TYPE'
  1311.      (String, default "meta".)  Select a display type or output format
  1312.      of TYPE, which may be one of the strings "X", "ps", "fig", "hpgl",
  1313.      "tek", and "meta".  These refer respectively to the
  1314.      X Window System, `idraw'-editable Postscript, the format used by
  1315.      the `xfig' drawing editor, the Hewlett-Packard Graphics Language,
  1316.      Tektronix format, and device-independent GNU metafile format.
  1317. `-p N'
  1318. `--page-number N'
  1319.      (Positive integer.) Display only page number N, within the
  1320.      metafile or sequence of metafiles that is being translated.
  1321.      Metafiles may consist of one or more pages, numbered beginning
  1322.      with 1.
  1323.      The default behavior, if `-p' is not used, is to display all pages.
  1324.      For example, `plot -T X' displays each page in its own X window.
  1325.      If the `-T fig' option is used, the default behavior is to display
  1326.      only the first page, since files to be edited by `xfig' may
  1327.      contain only a single page of graphics.
  1328.      Most metafiles produced by the GNU plotting utilities (e.g., by raw
  1329.      `graph') contain only a single page.
  1330. `--bitmap-size BITMAP_SIZE'
  1331.      (String, default "570x570".)  Set the size of the graphics display
  1332.      in which the plot will be drawn, in terms of pixels, to be
  1333.      BITMAP_SIZE.  This is relevant only to `graph -T X', for which the
  1334.      graphics display is an X window.  If you choose a rectangular
  1335.      (non-square) window size, the fonts in the plot will be scaled
  1336.      anisotropically, i.e., by different factors in the horizontal and
  1337.      vertical direction.  This requires an X11R6 display.  Any font that
  1338.      cannot be scaled in this way will be replaced by a default scalable
  1339.      font, such as the Hershey vector font "HersheySerif".
  1340.      The environment variable `BITMAPSIZE' can equally well be used to
  1341.      specify the window size.  For backward compatibility, the
  1342.      X resource `Xplot.geometry', which can be set by the user, may be
  1343.      used instead.
  1344. `--max-line-length MAX_LINE_LENGTH'
  1345.      (Integer, default 500.) Set the maximum number of points that a
  1346.      polygonal line may contain, before it is flushed to the display
  1347.      device, to equal MAX_LINE_LENGTH.  If this flushing occurs, the
  1348.      polygonal line will be split into two or more sub-lines, though
  1349.      the splitting should not be noticeable.  Splitting will not take
  1350.      place if the line is the boundary of a filled polygon.
  1351.      The reason for splitting long polygonal lines is that some display
  1352.      devices (e.g., old Postscript printers and HP-GL plotters) have
  1353.      limited buffer sizes.  The environment variable `MAX_LINE_LENGTH'
  1354.      can also be used to specify the maximum line length.  This option
  1355.      has no effect on `plot -T tek' or raw `plot', since they draw
  1356.      polylines in real time and have no buffer limitations.
  1357. `--page-size PAGESIZE'
  1358.      (String, default "letter".) Set the size of the page on which the
  1359.      plot will be positioned.  This is relevant only to `plot -T ps',
  1360.      `plot -T fig', and `plot -T hpgl'.  "letter" means an 8.5in by
  1361.      11in page.  Any ISO page size in the range "a0"..."a4" or ANSI
  1362.      page size in the range "a"..."e" may be specified ("letter" is an
  1363.      alias for "a" and "tabloid" is an alias for "b").  "legal" and
  1364.      "ledger" are recognized page sizes also.  The environment variable
  1365.      `PAGESIZE' can equally well be used to specify the page size.
  1366.      For `plot -T ps', the graphics display within which the plot is
  1367.      drawn will be a square region centered on the specified page and
  1368.      occupying its full width.  For `plot -T fig', the graphics display
  1369.      will be a square region located in the upper left corner of an
  1370.      `xfig' display, with width equal to the width of the specified
  1371.      page.  For `plot -T hpgl', fine control over the positioning of
  1372.      the graphics display on the page may be accomplished by setting
  1373.      certain environment variables (*note plot Environment::.).
  1374.    The following options set the initial values of additional drawing
  1375. parameters.  All of these may be overridden by directives in the
  1376. metafile itself.  In fact, these options are useful mostly for plotting
  1377. old metafiles in the pre-GNU `plot(5)' format, which did not include
  1378. such directives.
  1379. `--bg-color NAME'
  1380.      (String, default "white".)  Set the color used for the drawing
  1381.      background to be NAME.  This is currently relevant only to `plot
  1382.      -T X'.  An unrecognized name sets the color to the default.  For
  1383.      information on what names are recognized, see *Note Color Names::.
  1384.      The environment variable `BG_COLOR' can equally well be used to
  1385.      specify the background color.
  1386. `-f FONT_SIZE'
  1387. `--font-size FONT_SIZE'
  1388.      (Float, default 0.0525.)  Set the initial size of the font used
  1389.      for rendering text, as a fraction of the width of the display
  1390.      device, to FONT_SIZE.
  1391. `-F FONT_NAME'
  1392. `--font-name FONT_NAME'
  1393.      (String, default "Helvetica" except for `plot -T hpgl' and `plot
  1394.      -T tek', for which "HersheySerif" is the default.)  Set the font
  1395.      initially used for text (i.e., for `labels') to FONT_NAME.  Font
  1396.      names are case-insensitive.  If the specified font is not
  1397.      available, the default font will be used.  Which fonts are
  1398.      available depends on which `-T' option is used.  For a list of all
  1399.      fonts, see *Note Text Fonts::.  The `plotfont' utility will
  1400.      produce a character map of any available font.  *Note plotfont::.
  1401. `-W LINE_WIDTH'
  1402. `--line-width LINE_WIDTH'
  1403.      (Float, default -1.0.)  Set the width of lines, as a fraction of
  1404.      the width of the display, to LINE_WIDTH.  A negative value means
  1405.      that the default value provided by the `libplot' graphics library
  1406.      should be used.  This value is device-dependent.  The
  1407.      interpretation of zero line width is also device-dependent (on some
  1408.      devices, a zero-width line is the thinnest line that can be drawn;
  1409.      on others, a zero-width line is invisible).
  1410.      `plot -T tek' does not support drawing lines with other than a
  1411.      default width, and `plot -T hpgl' does not support doing so if the
  1412.      environment variable `HPGL_VERSION' is set to a value less
  1413.      than "2" (the default).
  1414. `--pen-color NAME'
  1415.      (String, default "black".)  Set the pen color to be NAME.  An
  1416.      unrecognized name sets the pen color to the default.  For
  1417.      information on what color names are recognized, see *Note Color
  1418.      Names::.
  1419.    The following option is relevant only to raw `plot', i.e., relevant
  1420. only if no output type is specified with the `-T' option.  In this case
  1421. `plot' outputs a graphics metafile, which may be translated to other
  1422. formats by a second invocation of `plot'.
  1423. `--portable-output'
  1424.      Output the portable (human-readable) version of GNU metafile
  1425.      format, rather than a binary version (the default).
  1426.    `plot' will automatically determine which type of GNU metafile
  1427. format the input is in.  There are two types: binary (the default) and
  1428. portable (human-readable).  The binary format is machine-dependent.
  1429. *Note Metafiles::.
  1430.    For compatibility with older plotting software, the reading of input
  1431. files in the pre-GNU `plot(5)' format is also supported.  This is
  1432. normally a binary format, with each integer in the metafile represented
  1433. as a pair of bytes.  The order of the two bytes is machine dependent.
  1434. You may specify that input file(s) are in plot(5) format rather than
  1435. ordinary GNU metafile format by using either the `-h' option ("high
  1436. byte first") or the `-l' option ("low byte first"), whichever is
  1437. appropriate.  Some non-GNU systems support an ASCII (human-readable)
  1438. variant of plot(5) format.  You may specify that the input is in this
  1439. format by using the `-A' option.  Irrespective of the variant, a file
  1440. in plot(5) format includes only one page of graphics.
  1441. `--high-byte-first-input'
  1442.      Input file(s) are assumed to be in traditional `plot(5)' metafile
  1443.      format, with the high-order byte of each integer occurring first.
  1444. `--low-byte-first-input'
  1445.      Input file(s) are assumed to be in traditional `plot(5)' metafile
  1446.      format, with the low-order byte of each integer occurring first.
  1447. `--ascii-input'
  1448.      Input file(s) are assumed to be in the ASCII variant of traditional
  1449.      `plot(5)' metafile format.
  1450.    The following options request information.
  1451. `--help'
  1452.      Print a list of command-line options, and then exit.
  1453. `--help-fonts'
  1454.      Print a table of available fonts, and then exit.  The table will
  1455.      depend on which display type or output format is specified with
  1456.      the `-T' option.  `plot -T X', `plot -T ps', and `plot -T fig'
  1457.      each support the 35 standard Postscript fonts.  `plot -T hpgl'
  1458.      supports the 45 standard PCL 5 fonts.  All four, together with
  1459.      `plot -T hpgl' and `plot -T tek', support a set of 22 Hershey
  1460.      vector fonts.  Raw `plot' in principle supports any of these 102
  1461.      fonts, since its output may be translated to any other format by a
  1462.      later invocation of `plot'.
  1463. `--list-fonts'
  1464.      Like `--help-fonts', but lists the fonts in a single column to
  1465.      facilitate piping to other programs.  If no display type or output
  1466.      format is specified with the `-T' option, the full set of supported
  1467.      fonts is listed.
  1468. `--version'
  1469.      Print the version number of `plot' and the plotting utilities
  1470.      package, and exit.
  1471. File: plotutils.info,  Node: plot Environment,  Prev: plot Invocation,  Up: plot
  1472. Environment variables
  1473. =====================
  1474.    The behavior of `plot' is affected by several environment variables.
  1475. We have already mentioned the environment variables `BITMAPSIZE',
  1476. `PAGESIZE', `BG_COLOR', and `MAX_LINE_LENGTH'.  They serve as backups
  1477. for the options `--bitmap-size', `--page-size', `--bg-color', and
  1478. `--max-line-length'.  The remaining environment variables are specific
  1479. to individual display types.  They control device driver parameters.
  1480.    `plot -T X', which pops up a window on an X Window System display
  1481. and draws graphics in it, checks the `DISPLAY' environment variable.
  1482. The value of this variable determines the display on which the window
  1483. will be popped up.
  1484.    `plot -T hpgl', which produces Hewlett-Packard Graphics Language
  1485. output, is affected by several environment variables.  The most
  1486. important is `HPGL_VERSION', which may be set to "1", "1.5", or "2"
  1487. (the default).  "1" means that the output should be generic HP-GL,
  1488. "1.5" means that the output should be suitable for the HP7550A graphics
  1489. plotter and the HP758x, HP7595A and HP7596A drafting plotters (HP-GL
  1490. with some HP-GL/2 extensions), and "2" means that the output should be
  1491. modern HP-GL/2.  If the version is "1" or "1.5" then the only available
  1492. fonts will be vector fonts, and all lines will be drawn with a default
  1493. width (the `-W' option will not work).  Additionally, if the version
  1494. is "1" then the filling of arbitrary curves with solid color will not
  1495. be supported (circles and rectangles aligned with the coordinate axes
  1496. may be filled, though).
  1497.    The position of the `plot -T hpgl' graphics display on the page can
  1498. be adjusted by setting the `HPGL_XOFFSET' and `HPGL_YOFFSET'
  1499. environment variables, which may be specified in centimeters,
  1500. millimeters, or inches.  For example, an offset could be specified as
  1501. "2cm" or "1.2in".  Also, the display can be rotated 90 degrees
  1502. counterclockwise on the page by setting the `HPGL_ROTATE' environment
  1503. variable to "yes".  Besides "no" and "yes", recognized values for this
  1504. variable are "0", "90", "180", and "270".  "no" and "yes" are
  1505. equivalent to "0" and "90", respectively.  "180" and "270" are
  1506. supported only if `HPGL_VERSION' is "2" (the default).
  1507.    *Opaque* filling and the drawing of visible white lines are
  1508. supported only if `HPGL_VERSION' is "2" and the environment variable
  1509. `HPGL_OPAQUE_MODE' is "yes" (the default).  If the value is "no" then
  1510. opaque filling will not be used, and white lines (if any), which are
  1511. normally drawn with pen #0, will not be drawn.  This feature is to
  1512. accommodate older HP-GL/2 devices.  HP-GL/2 pen plotters, for example,
  1513. do not support opacity or the use of pen #0 to draw visible white
  1514. lines.  Some older HP-GL/2 devices reportedly malfunction if asked to
  1515. draw opaque objects.
  1516.    By default, `plot -T hpgl' will draw with a fixed set of pens.
  1517. Which pens are present may be specified by setting the `HPGL_PENS'
  1518. environment variable.  If `HPGL_VERSION' is "1", the default value of
  1519. `HPGL_PENS' is "1=black"; if `HPGL_VERSION' is "1.5" or "2", the
  1520. default value of `HPGL_PENS' is
  1521. "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan".  The format
  1522. should be self-explanatory.  By setting `HPGL_PENS', you may specify a
  1523. color for any pen in the range #1...#31.  For information on what color
  1524. names are recognized, see *Note Color Names::.  Pen #1 must always be
  1525. present, though it need not be black. Any other pen in the range
  1526. #1...#31 may be omitted.
  1527.    If `HPGL_VERSION' is "2" then `plot -T hpgl' will also be affected
  1528. by the environment variable `HPGL_ASSIGN_COLORS'.  If the value of this
  1529. variable is "yes", then `plot -T hpgl' will not be restricted to the
  1530. palette specified in `HPGL_PENS': it will assign colors to "logical
  1531. pens" in the range #1...#31, as needed.  The default value is "no"
  1532. because other than color LaserJet printers and DesignJet plotters, not
  1533. many HP-GL/2 devices allow the assignment of colors to logical pens.
  1534.    `plot -T tek', which produces output for a Tektronix terminal or
  1535. emulator, checks the `TERM' environment variable.  If the value of
  1536. `TERM' is `xterm', `xterms', or `kterm', it is taken as a sign that the
  1537. current application is running in an X Window System VT100 terminal
  1538. emulator: an `xterm'.  Before drawing graphics, `plot -T tek' will emit
  1539. an escape sequence that causes the terminal emulator's auxiliary
  1540. Tektronix window, which is normally hidden, to pop up.  After the
  1541. graphics are drawn, an escape sequence that returns control to the
  1542. original VT100 window will be emitted.  The Tektronix window will
  1543. remain on the screen.
  1544.    If the value of `TERM' is `kermit', `ansi.sys', `ansissys',
  1545. `ansi.sysk', or `ansisysk', it is taken as a sign that the current
  1546. application is running in the VT100 terminal emulator provided by the
  1547. MS-DOS version of `kermit'.  Before drawing graphics, `plot -T tek'
  1548. will emit an escape sequence that switches the terminal emulator to
  1549. Tektronix mode.  Also, some of the Tektronix control codes emitted by
  1550. `plot -T tek' will be `kermit'-specific.  There will be a limited
  1551. amount of color support, which is not normally the case (the 16
  1552. `ansi.sys' colors will be supported).  After drawing graphics, `plot -T
  1553. tek' will emit an escape sequence that returns the emulator to VT100
  1554. mode.  The key sequence `ALT minus' can be employed manually within
  1555. `kermit' to switch between the two modes.
  1556. File: plotutils.info,  Node: tek2plot,  Next: plotfont,  Prev: plot,  Up: Top
  1557. The `tek2plot' Program
  1558. **********************
  1559. * Menu:
  1560. * tek2plot Introduction::     What tek2plot is used for
  1561. * tek2plot Invocation::       Command-line options
  1562. * tek2plot Environment::      Environment variables
  1563. File: plotutils.info,  Node: tek2plot Introduction,  Next: tek2plot Invocation,  Prev: tek2plot,  Up: tek2plot
  1564. What `tek2plot' is used for
  1565. ===========================
  1566.    GNU `tek2plot' is a command-line Tektronix translator.  It displays
  1567. Tektronix graphics files, or translates them to other formats.  The
  1568. supported output formats are the same formats that are supported by the
  1569. GNU `graph' and `plot' utilities.  `tek2plot' will take input from a
  1570. file specified on the command line or from standard input, just as the
  1571. plot filter `plot' does.
  1572.    Tektronix graphics files are produced by many legacy applications.
  1573. A directory containing sample Tektronix files, which you may experiment
  1574. with, is distributed along with the GNU plotting utilities.  On most
  1575. systems it is installed as `/usr/share/tek2plot' or
  1576. `/usr/local/share/tek2plot'.
  1577.    Tektronix graphics format is defined as a noninteractive version of
  1578. the graphics format understood by Tektronix 4010/4014 terminals, as
  1579. documented in the `4014 Service Manual', Tektronix Inc., 1974
  1580. (Tektronix Part #070-1648-00).  `tek2plot' does not support interactive
  1581. features such as GIN mode and status enquiry.  However, it does support
  1582. a few features of popular Tektronix emulators, such as the color
  1583. extensions supported by the Tektronix emulator contained in the MS-DOS
  1584. version of `kermit'.
  1585. File: plotutils.info,  Node: tek2plot Invocation,  Next: tek2plot Environment,  Prev: tek2plot Introduction,  Up: tek2plot
  1586. `tek2plot' command-line options
  1587. ===============================
  1588.    The `tek2plot' program translates the Tektronix graphics files
  1589. produced by many legacy applications to other formats.  The output
  1590. format or display type is specified with the `-T' option.  The possible
  1591. output formats are the same six formats that are supported by the GNU
  1592. `graph' and `plot' programs.
  1593.    Input file names may be specified anywhere on the command line.  That
  1594. is, the relative order of file names and command-line options does not
  1595. matter.  If no file names are specified, or the file name `-' is
  1596. specified, the standard input is read.
  1597.    The full set of command-line options is listed below.  There are
  1598. three sorts of option:
  1599.   1. General options.
  1600.   2. Options relevant only to raw `tek2plot', i.e., relevant only if no
  1601.      display type or output format is specified with the `-T' option.
  1602.   3. Options requesting information (e.g., `--help').
  1603. Each option that takes an argument is followed, in parentheses, by the
  1604. type and default value of the argument.
  1605.    The following are general options.
  1606. `-T TYPE'
  1607. `--display-type TYPE'
  1608.      (String, default "meta".)  Select a display type or output format
  1609.      of TYPE, which may be one of the strings "X", "ps", "fig", "hpgl",
  1610.      "tek", and "meta".  These refer respectively to the
  1611.      X Window System, `idraw'-editable Postscript, the format used by
  1612.      the `xfig' drawing editor, the Hewlett-Packard Graphics Language,
  1613.      Tektronix format, and device-independent GNU metafile format.
  1614. `-p N'
  1615. `--page-number N'
  1616.      (Nonnegative integer.) Display only page number N, within the
  1617.      Tektronix file or sequence of Tektronix files that is being
  1618.      translated.  Tektronix files may consist of one or more pages,
  1619.      numbered beginning with zero.
  1620.      The default behavior, if the `-p' option is not used, is to display
  1621.      all nonempty pages in succession.  For example, `tek2plot -T X'
  1622.      displays each page in its own X window.  If the `-T fig' option is
  1623.      used, the default behavior is to display only the first nonempty
  1624.      Tektronix page, since files to be edited by `xfig' may contain only
  1625.      a single page of graphics.
  1626.      Most Tektronix files consist of either one page (page #0) or two
  1627.      pages (an empty page #0, and page #1).  Tektronix files produced
  1628.      by the GNU plotting utilities (e.g., by `graph -T tek') are
  1629.      normally of the latter sort.
  1630. `-F FONT_NAME'
  1631. `--font-name FONT_NAME'
  1632.      (String, default "Courier" except for `tek2plot -T hpgl', for which
  1633.      "HersheySerif" is the default.)  Set the font used for text to
  1634.      FONT_NAME.  Font names are case-insensitive.  If a font outside
  1635.      the Courier family is chosen, the `--position-chars' option (see
  1636.      below) should probably be used.  For a list of all fonts, see
  1637.      *Note Text Fonts::.  If the specified font is not available, the
  1638.      default font will be used.
  1639. `-W LINE_WIDTH'
  1640. `--line-width LINE_WIDTH'
  1641.      (Float, default -1.0.)  Set the width of lines, as a fraction of
  1642.      the width of the display, to LINE_WIDTH.  A negative value means
  1643.      that the default value provided by the `libplot' graphics library
  1644.      should be used.  This value is device-dependent.  The
  1645.      interpretation of zero line width is also device-dependent (on some
  1646.      devices, a zero-width line is the thinnest line that can be drawn;
  1647.      on others, a zero-width line is invisible).
  1648.      `tek2plot -T hpgl' does not support drawing lines with other than a
  1649.      default width if the environment variable `HPGL_VERSION' is set to
  1650.      a value less than "2" (the default).
  1651. `--bg-color NAME'
  1652.      (String, default "white".)  Set the color used for the background
  1653.      to be NAME.  This is currently relevant only to `tek2plot -T X'.
  1654.      An unrecognized name sets the color to the default.  For
  1655.      information on what names are recognized, see *Note Color Names::.
  1656.      The environment variable `BG_COLOR' can equally well be used to
  1657.      specify the background color.
  1658. `--bitmap-size BITMAP_SIZE'
  1659.      (String, default "570x570".)  Set the size of the graphics display
  1660.      in which the plot will be drawn, in terms of pixels, to be
  1661.      BITMAP_SIZE.  This is relevant only to `graph -T X', for which the
  1662.      graphics display is an X window.  If you choose a rectangular
  1663.      (non-square) window size, the fonts in the plot will be scaled
  1664.      anisotropically, i.e., by different factors in the horizontal and
  1665.      vertical direction.  This requires an X11R6 display.  Any font that
  1666.      cannot be scaled in this way will be replaced by a default scalable
  1667.      font, such as the Hershey vector font "HersheySerif".
  1668.      The environment variable `BITMAPSIZE' can equally well be used to
  1669.      specify the window size.  For backward compatibility, the
  1670.      X resource `Xplot.geometry', which can be set by the user, may be
  1671.      used instead.
  1672. `--max-line-length MAX_LINE_LENGTH'
  1673.      (Integer, default 500.) Set the maximum number of points that a
  1674.      polygonal line may contain, before it is flushed to the display
  1675.      device, to equal MAX_LINE_LENGTH.  If this flushing occurs, the
  1676.      polygonal line will be split into two or more sub-lines, though
  1677.      the splitting should not be noticeable.
  1678.      The reason for splitting long polygonal lines is that some display
  1679.      devices (e.g., old Postscript printers and HP-GL plotters) have
  1680.      limited buffer sizes.  The environment variable `MAX_LINE_LENGTH'
  1681.      can also be used to specify the maximum line length.  This option
  1682.      has no effect on raw `tek2plot', since it draws polylines in real
  1683.      time and has no buffer limitations.
  1684. `--page-size PAGESIZE'
  1685.      (String, default "letter".) Set the size of the page on which the
  1686.      plot will be positioned.  This is relevant only to `tek2plot -T
  1687.      ps', `tek2plot -T fig', and `tek2plot -T hpgl'.  "letter" means an
  1688.      8.5in by 11in page.  Any ISO page size in the range "a0"..."a4" or
  1689.      ANSI page size in the range "a"..."e" may be specified ("letter"
  1690.      is an alias for "a" and "tabloid" is an alias for "b").  "legal"
  1691.      and "ledger" are recognized page sizes also.  The environment
  1692.      variable `PAGESIZE' can equally well be used to specify the page
  1693.      size.
  1694.      For `tek2plot -T ps', the graphics display within which the plot is
  1695.      drawn will be a square region centered on the specified page and
  1696.      occupying its full width.  For `tek2plot -T fig', the graphics
  1697.      display will be a square region located in the upper left corner
  1698.      of an `xfig' display, with width equal to the width of the
  1699.      specified page.  For `tek2plot -T hpgl', fine control over the
  1700.      positioning of the graphics display on the page can be
  1701.      accomplished by setting certain environment variables (*note
  1702.      tek2plot Environment::.).
  1703. `--pen-color NAME'
  1704.      (String, default "black".)  Set the pen color to be NAME.  An
  1705.      unrecognized name sets the pen color to the default.  For
  1706.      information on what color names are recognized, see *Note Color
  1707.      Names::.
  1708. `--position-chars'
  1709.      Position the characters in each text string individually on the
  1710.      display.  If the text font is not a member of the Courier family,
  1711.      and especially if it is not a fixed-width font, this option is
  1712.      recommended.  It will improve the appearance of text strings, at
  1713.      the price of making it difficult to edit the output file with
  1714.      `xfig' or `idraw'.
  1715. `--use-tek-fonts'
  1716.      Use the bitmap fonts that were used on the original Tektronix
  1717.      4010/4014 terminal.  This option is relevant only to `tek2plot
  1718.      -T X'.  The four relevant bitmap fonts are distributed with most
  1719.      versions of the plotting utilities package, under the names
  1720.      `tekfont0'...`tekfont3'.  They can easily be installed on any
  1721.      modern X Window System display.  For this option to work properly,
  1722.      you must also select a window size of 1024x1024 pixels, either by
  1723.      using the `--bitmap-size 1024x1024' option or by setting the value
  1724.      of the `Xplot.geometry' resource.  The reason for this restriction
  1725.      is that bitmap fonts, unlike the scalable fonts that the plotting
  1726.      utilities normally use, cannot be rescaled.
  1727.      This option is useful only if you have a file in Tektronix format
  1728.      that draws text using native Tektronix fonts.  Tektronix files
  1729.      produced by the GNU plotting utilities (e.g., by `graph -T tek')
  1730.      do not use native Tektronix fonts to draw text.
  1731.    The following option is relevant only to raw `tek2plot', i.e.,
  1732. relevant only if no display type or output format is specified with the
  1733. `-T' option.  In this case `tek2plot' outputs a graphics metafile,
  1734. which may be translated to other formats by invoking `plot'.
  1735. `--portable-output'
  1736.      Output the portable (human-readable) version of GNU metafile
  1737.      format, rather than a binary version (the default).
  1738.    The following options request information.
  1739. `--help'
  1740.      Print a list of command-line options, and then exit.
  1741. `--help-fonts'
  1742.      Print a table of available fonts, and then exit.  The table will
  1743.      depend on which display type or output format is specified with
  1744.      the `-T' option.  `tek2plot -T X', `tek2plot -T ps', and `tek2plot
  1745.      -T fig' each support the 35 standard Postscript fonts.  `tek2plot
  1746.      -T hpgl' supports the 45 standard PCL 5 fonts.  All four, together
  1747.      with `tek2plot -T hpgl', support a set of 22 Hershey vector fonts.
  1748.      Raw `tek2plot' in principle supports any of these 102 fonts,
  1749.      since its output must be translated to other formats with `plot'.
  1750. `--list-fonts'
  1751.      Like `--help-fonts', but lists the fonts in a single column to
  1752.      facilitate piping to other programs.  If no display type or output
  1753.      format is specified with the `-T' option, the full set of supported
  1754.      fonts is listed.
  1755. `--version'
  1756.      Print the version number of `tek2plot' and the plotting utilities
  1757.      package, and exit.
  1758. File: plotutils.info,  Node: tek2plot Environment,  Prev: tek2plot Invocation,  Up: tek2plot
  1759. Environment variables
  1760. =====================
  1761.    The behavior of `tek2plot' is affected by several environment
  1762. variables, which are the same as those that affect `graph' and `plot'.
  1763. For convenience, we list them here.
  1764.    We have already mentioned the environment variables `BITMAPSIZE',
  1765. `PAGESIZE', `BG_COLOR', and `MAX_LINE_LENGTH'.  They serve as backups
  1766. for the options `--bitmap-size', `--page-size', `--bg-color', and
  1767. `--max-line-length'.  The remaining environment variables are specific
  1768. to individual display devices.  They control device driver parameters.
  1769.    `tek2plot -T X', which pops up a window on an X Window System
  1770. display and draws graphics in it, checks the `DISPLAY' environment
  1771. variable.  The value of this variable determines the display on which
  1772. the window will be popped up.
  1773.    `tek2plot -T hpgl', which produces Hewlett-Packard Graphics Language
  1774. output, is affected by several environment variables.  The most
  1775. important is `HPGL_VERSION', which may be set to "1", "1.5", or "2"
  1776. (the default).  "1" means that the output should be generic HP-GL,
  1777. "1.5" means that the output should be suitable for the HP7550A graphics
  1778. plotter and the HP758x, HP7595A and HP7596A drafting plotters (HP-GL
  1779. with some HP-GL/2 extensions), and "2" means that the output should be
  1780. modern HP-GL/2.  If the version is "1" or "1.5" then the only available
  1781. fonts will be vector fonts, and all lines will be drawn with a default
  1782. width (the `-W' option will not work).
  1783.    The position of the `tek2plot -T hpgl' graphics display on the page
  1784. can be adjusted by setting the `HPGL_XOFFSET' and `HPGL_YOFFSET'
  1785. environment variables, which may be specified in centimeters,
  1786. millimeters, or inches.  For example, an offset could be specified as
  1787. "2cm" or "1.2in".  Also, the display can be rotated 90 degrees
  1788. counterclockwise on the page by setting the `HPGL_ROTATE' environment
  1789. variable to "yes".  Besides "no" and "yes", recognized values for this
  1790. variable are "0", "90", "180", and "270".  "no" and "yes" are
  1791. equivalent to "0" and "90", respectively.  "180" and "270" are
  1792. supported only if `HPGL_VERSION' is "2" (the default).
  1793.    The drawing of visible white lines is supported only if
  1794. `HPGL_VERSION' is "2" and the environment variable `HPGL_OPAQUE_MODE'
  1795. is "yes" (the default).  If the value is "no" then white lines
  1796. (if any), which are normally drawn with pen #0, will not be drawn.
  1797. This feature is to accommodate older HP-GL/2 devices.  HP-GL/2 pen
  1798. plotters, for example, do not support the use of pen #0 to draw visible
  1799. white lines.  Some older HP-GL/2 devices may, in fact, malfunction if
  1800. asked to draw opaque objects.
  1801.    By default, `tek2plot -T hpgl' will draw with a fixed set of pens.
  1802. Which pens are present may be specified by setting the `HPGL_PENS'
  1803. environment variable.  If `HPGL_VERSION' is "1", the default value of
  1804. `HPGL_PENS' is "1=black"; if `HPGL_VERSION' is "1.5" or "2", the
  1805. default value of `HPGL_PENS' is
  1806. "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan".  The format
  1807. should be self-explanatory.  By setting `HPGL_PENS', you may specify a
  1808. color for any pen in the range #1...#31.  For information on what color
  1809. names are recognized, see *Note Color Names::.  Pen #1 must always be
  1810. present, though it need not be black. Any other pen in the range
  1811. #1...#31 may be omitted.
  1812.    If `HPGL_VERSION' is "2" then `tek2plot -T hpgl' will also be
  1813. affected by the environment variable `HPGL_ASSIGN_COLORS'.  If the
  1814. value of this variable is "yes", then `tek2plot -T hpgl' will not be
  1815. restricted to the palette specified in `HPGL_PENS': it will assign
  1816. colors to "logical pens" in the range #1...#31, as needed.  The default
  1817. value is "no" because other than color LaserJet printers and DesignJet
  1818. plotters, not many HP-GL/2 devices allow the assignment of colors to
  1819. logical pens.
  1820. File: plotutils.info,  Node: plotfont,  Next: spline,  Prev: tek2plot,  Up: Top
  1821. The `plotfont' Utility
  1822. **********************
  1823. * Menu:
  1824. * plotfont Examples::         How to use plotfont
  1825. * plotfont Invocation::       Command-line options
  1826. * plotfont Environment::      Environment variables
  1827. File: plotutils.info,  Node: plotfont Examples,  Next: plotfont Invocation,  Prev: plotfont,  Up: plotfont
  1828. How to use `plotfont'
  1829. =====================
  1830.    GNU `plotfont' is a simple utility that will produce a character map
  1831. for any font available to the GNU plotting utilities `graph', `plot',
  1832. and `tek2plot', and the GNU `libplot' graphics library on which they
  1833. are based.  The map may be displayed on an X Window System display, or
  1834. produced in any of five output formats.
  1835.    Which fonts are available depends on the choice of display or output
  1836. format.  To get a list of the available fonts, use the `--help-fonts'
  1837. option.  For example,
  1838.      plotfont -T ps --help-fonts
  1839. will list the fonts that are available when producing Postscript output.
  1840. One of these fonts is "Times-Roman".  Doing
  1841.      plotfont -T ps Times-Roman > map.ps
  1842. will produce a character map of the lower half of this font, which
  1843. consists of printable ASCII characters.  The map will be a 12x8 grid,
  1844. with a character centered in each grid cell.  If you include the `-2'
  1845. option, you will get a map of the upper half of the font.
  1846.    Most built-in fonts are ISO-Latin-1 fonts, which means that the upper
  1847. half is arranged according to the ISO-Latin-1 encoding.  The
  1848. "HersheyCyrillic" font is one that is not.  If you do
  1849.      plotfont -T ps -2 HersheyCyrillic > map.ps
  1850. you will get a map that illustrates its arrangment, which is called
  1851. KOI8-R.  The KOI8-R arrangement is the standard for Unix and networking
  1852. applications in the former Soviet Union.  So-called dingbats fonts, such
  1853. as "ZapfDingbats" and "Wingdings", also have an individualistic layout.
  1854. The Wingdings font is available when producing output in HP-GL or
  1855. HP-GL/2 format.  If you do
  1856.      plotfont -T hpgl Wingdings > map.plt
  1857. you will get a Wingdings character map, in HP-GL/2 format, that may be
  1858. imported into any application that understands HP-GL/2.  In most
  1859. installations of the plotting utilities, the Wingdings font is not
  1860. available when producing Postscript output.
  1861.    In all, 102 fonts that are built into the plotting utilities.  *Note
  1862. Text Fonts::.  If you are using the plotting utilities to display
  1863. output on an X display, you are not restricted to the built-in fonts.
  1864. Doing
  1865.      plotfont -T X --help-fonts
  1866. produces a list of the built-in fonts that are available, including both
  1867. Hershey and Postscript fonts.  But fonts available on your X display
  1868. may also be used.  The `xlsfonts' command will list the fonts available
  1869. on your X display, most font names being given in what is called XLFD
  1870. format.  The plotting utilities refer to X fonts by shortened versions
  1871. of their XLFD names.  For example, the font "Utopia-Regular" is
  1872. available on many X displays.  Its XLFD name is
  1873. "-adobe-utopia-medium-r-normal-0-0-0-0-p-0-iso8859-1", and its
  1874. shortened XLFD name is "utopia-medium-r-normal".  If you do
  1875.      plotfont -T X utopia-medium-r-normal
  1876. then a character map for this font will be displayed in a popped-up
  1877. X window.
  1878.    When using the `-T X' option, you may also use the `--bitmap-size'
  1879. option to choose the size of the popped-up window.  Modern X displays
  1880. can scale fonts by different amounts in the horizontal and vertical
  1881. directions.  If, for example, you add `--bitmap-size 600x300' to the
  1882. above command line, both the character map and the Utopia-Regular font
  1883. within it will be scaled in this way.  If your X display does not
  1884. support font scaling, a scalable font will be substituted.
  1885. File: plotutils.info,  Node: plotfont Invocation,  Next: plotfont Environment,  Prev: plotfont Examples,  Up: plotfont
  1886. `plotfont' command-line options
  1887. ===============================
  1888.    The `plotfont' font display utility will produce a character map for
  1889. any of the fonts available to the GNU plotting utilities `graph',
  1890. `plot', and `tek2plot', and the GNU `libplot' graphics library on which
  1891. they are based.  The map may be produced in any supported output
  1892. format, or displayed on an `X Window' System display.  The display type
  1893. or output format is specified with the `-T' option.
  1894.    The names of the fonts for which a character map will be produced may
  1895. appear anywhere on the `plotfont' command line.  That is, the relative
  1896. order of font names and command-line options does not matter.  The
  1897. possible options are listed below.  There are three sorts of option:
  1898.   1. General options.
  1899.   2. Options relevant only to raw `plotfont', i.e., relevant only if no
  1900.      display type or output format is specified with the `-T' option.
  1901.   3. Options requesting information (e.g., `--help').
  1902. Each option that takes an argument is followed, in parentheses, by the
  1903. type and default value of the argument.
  1904.    The following are general options.
  1905. `--lower-half'
  1906.      Generate a character map for the lower half of each specified font.
  1907.      This is the default.
  1908. `--upper-half'
  1909.      Generate a character map for the upper half of each specified font.
  1910. `--octal'
  1911.      Number the characters in octal rather than in decimal (the
  1912.      default).
  1913. `--hexadecimal'
  1914.      Number the characters in hexadecimal rather than in decimal (the
  1915.      default).
  1916. `--box'
  1917.      Surround each character with a box, showing its extent to left and
  1918.      right.  The default is not to do this.
  1919. `-J PAGE'
  1920. `--jis-page PAGE'
  1921.      Generate a character map for page PAGE of a Japanese font encoded
  1922.      according to JIS [Japanese Industrial Standard] X0208.  PAGE must
  1923.      be in the range 33...126.  This option may be used only with the
  1924.      HersheyEUC [Extended Unix Code] font.  If used, it overrides the
  1925.      `-1' and `-2' options.
  1926.      The JIS X0208 standard represents each encoded character as a pair
  1927.      of bytes: a page number and a character number, both in the range
  1928.      0x21...0x7e, i.e., 33...126.  The HersheyEUC font implements this
  1929.      standard, and further encodes each character by setting the high
  1930.      bit on each of the two bytes.
  1931.      In HersheyEUC, Japanese syllabic characters (Hiragana and
  1932.      Katakana) are located on pages 35 and 36.  Japanese ideograms
  1933.      (Kanji) are located on pages 48 and above.
  1934. `-T TYPE'
  1935. `--display-type TYPE'
  1936.      (String, default "meta".)  Select a display type or output format
  1937.      of TYPE, which may be one of the strings "X", "ps", "fig", "hpgl",
  1938.      "tek", and "meta".  These refer respectively to the
  1939.      X Window System, `idraw'-editable Postscript, the format used by
  1940.      the `xfig' drawing editor, the Hewlett-Packard Graphics Language,
  1941.      Tektronix format, and device-independent GNU metafile format.
  1942.      Files to be edited by `xfig' may contain only a single page of
  1943.      graphics.  So if the `-T fig' option is used, a character map will
  1944.      be produced for only the first-specified font.
  1945. `--bg-color NAME'
  1946.      (String, default "white".)  Set the color used for the background
  1947.      to be NAME.  This is currently relevant only to `plotfont -T X'.
  1948.      An unrecognized name sets the color to the default.  For
  1949.      information on what names are recognized, see *Note Color Names::.
  1950.      The environment variable `BG_COLOR' can equally well be used to
  1951.      specify the background color.
  1952. `--bitmap-size BITMAP_SIZE'
  1953.      (String, default "570x570".)  Set the size of the graphics display
  1954.      in which a character map is drawn, in terms of pixels, to be
  1955.      BITMAP_SIZE.  This is relevant only to `plot2font -T X', for which
  1956.      the graphics display is an X window.  If you choose a rectangular
  1957.      (non-square) window size, the font in the character map will be
  1958.      scaled anisotropically, i.e., by different factors in the
  1959.      horizontal and vertical direction.  This requires an X11R6
  1960.      display.  If the font cannot be scaled in this way, it will be
  1961.      replaced by a default scalable font, such as the Hershey vector
  1962.      font "HersheySerif".
  1963.      The environment variable `BITMAPSIZE' can equally well be used to
  1964.      specify the window size.  For backward compatibility, the
  1965.      X resource `Xplot.geometry', which can be set by the user, may be
  1966.      used instead.
  1967. `--numbering-font-name FONT_NAME'
  1968.      (String, default "Helvetica" except for `plotfont -T hpgl' and
  1969.      `plotfont -T tek', for which "HersheySerif" is the default.)  Set
  1970.      the font used for the numbering of the characters in the character
  1971.      map(s) to be FONT_NAME.
  1972. `--page-size PAGESIZE'
  1973.      (String, default "letter".) Set the size of the page for which the
  1974.      character map(s) will be produced.  This is relevant only to
  1975.      `plotfont -T ps', `plotfont -T fig', and `plotfont -T hpgl'.
  1976.      "letter" means an 8.5in by 11in page.  Any ISO page size in the
  1977.      range "a0"..."a4" or ANSI page size in the range "a"..."e" may be
  1978.      specified ("letter" is an alias for "a" and "tabloid" is an alias
  1979.      for "b").  "legal" and "ledger" are recognized page sizes also.
  1980.      The environment variable `PAGESIZE' can equally well be used to
  1981.      specify the page size.
  1982.      For `plotfont -T ps', the graphics display within which each
  1983.      character map is drawn will be a square region centered on the
  1984.      page, and occupying its full width.  For `plotfont -T fig', the
  1985.      graphics display will be a square region located in the upper left
  1986.      corner of an `xfig' display, with width equal to the width of the
  1987.      specified page.  For `plotfont -T hpgl', fine control over the
  1988.      positioning of the graphics display on the page can be
  1989.      accomplished by setting certain environment variables (*note
  1990.      plotfont Environment::.).
  1991. `--pen-color NAME'
  1992.      (String, default "black".)  Set the pen color to be NAME.  An
  1993.      unrecognized name sets the pen color to the default.  For
  1994.      information on what color names are recognized, see *Note Color
  1995.      Names::.
  1996. `--title-font-name FONT_NAME'
  1997.      (String) Set the font used for the title of each character map to
  1998.      be FONT_NAME.  Normally the font used for the title is the same as
  1999.      the font whose character set is being displayed.  This option is
  2000.      useful when producing character maps for unusual fonts such as
  2001.      "ZapfDingbats" and "Wingdings".
  2002.    The following option is relevant only to raw `plotfont', i.e.,
  2003. relevant only if no display type or output format is specified with the
  2004. `-T' option.  In this case `plotfont' outputs a graphics metafile,
  2005. which may be translated to other formats by invoking `plot'.
  2006. `--portable-output'
  2007.      Output the portable (human-readable) version of GNU metafile
  2008.      format, rather than a binary version (the default).
  2009.    The following options request information.
  2010. `--help'
  2011.      Print a list of command-line options, and then exit.
  2012. `--help-fonts'
  2013.      Print a table of available fonts, and then exit.  The table will
  2014.      depend on which display type or output format is specified with
  2015.      the `-T' option.  `plotfont -T X', `plotfont -T ps', and `plotfont
  2016.      -T fig' each support the 35 standard Postscript fonts.  `plotfont
  2017.      -T hpgl' supports the 45 standard PCL 5 fonts.  All four, together
  2018.      with `plotfont -T hpgl', support a set of 22 Hershey vector fonts.
  2019.      Raw `plotfont' in principle supports any of these 102 fonts,
  2020.      since its output must be translated to other formats with `plot'.
  2021. `--list-fonts'
  2022.      Like `--help-fonts', but lists the fonts in a single column to
  2023.      facilitate piping to other programs.  If no display type or output
  2024.      format is specified with the `-T' option, the full set of supported
  2025.      fonts is listed.
  2026. `--version'
  2027.      Print the version number of `plotfont' and the plotting utilities
  2028.      package, and exit.
  2029. File: plotutils.info,  Node: plotfont Environment,  Prev: plotfont Invocation,  Up: plotfont
  2030. Environment variables
  2031. =====================
  2032.    The behavior of `plotfont' is affected by several environment
  2033. variables, which are the same as those that affect `graph', `plot', and
  2034. `tek2plot'.  For convenience, we list them here.
  2035.    We have already mentioned the environment variables `BITMAPSIZE',
  2036. `PAGESIZE', and `BG_COLOR'.  They serve as backups for the options
  2037. `--bitmap-size', `--page-size', and `--bg-color'.  The remaining
  2038. environment variables are specific to individual display devices.  They
  2039. control device driver parameters.
  2040.    `plotfont -T X', which pops up a window on an X Window System
  2041. display and draws a character map in it, checks the `DISPLAY'
  2042. environment variable.  The value of this variable determines the
  2043. display on which the window will be popped up.
  2044.    `plotfont -T hpgl', which produces Hewlett-Packard Graphics Language
  2045. output, is affected by several environment variables.  The most
  2046. important is `HPGL_VERSION', which may be set to "1", "1.5", or "2"
  2047. (the default).  "1" means that the output should be generic HP-GL,
  2048. "1.5" means that the output should be suitable for the HP7550A graphics
  2049. plotter and the HP758x, HP7595A and HP7596A drafting plotters (HP-GL
  2050. with some HP-GL/2 extensions), and "2" means that the output should be
  2051. modern HP-GL/2.  If the version is "1" or "1.5" then the only available
  2052. fonts will be vector fonts.
  2053.    The position of the `plotfont -T hpgl' character map on the page can
  2054. be adjusted by setting the `HPGL_XOFFSET' and `HPGL_YOFFSET'
  2055. environment variables, which may be specified in centimeters,
  2056. millimeters, or inches.  For example, an offset could be specified as
  2057. "2cm" or "1.2in".  Also, the map can be rotated 90 degrees
  2058. counterclockwise on the page by setting the `HPGL_ROTATE' environment
  2059. variable to "yes".  Besides "no" and "yes", recognized values for this
  2060. variable are "0", "90", "180", and "270".  "no" and "yes" are
  2061. equivalent to "0" and "90", respectively.  "180" and "270" are
  2062. supported only if `HPGL_VERSION' is "2" (the default).
  2063.    By default, `plotfont -T hpgl' will draw with a fixed set of pens.
  2064. Which pens are present may be specified by setting the `HPGL_PENS'
  2065. environment variable.  If `HPGL_VERSION' is "1", the default value of
  2066. `HPGL_PENS' is "1=black"; if `HPGL_VERSION' is "1.5" or "2", the
  2067. default value of `HPGL_PENS' is
  2068. "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan".  The format
  2069. should be self-explanatory.  By setting `HPGL_PENS', you may specify a
  2070. color for any pen in the range #1...#31.  For information on what color
  2071. names are recognized, see *Note Color Names::.  Pen #1 must always be
  2072. present, though it need not be black. Any other pen in the range
  2073. #1...#31 may be omitted.
  2074.    If `HPGL_VERSION' is "2" then `plotfont -T hpgl' will also be
  2075. affected by the environment variable `HPGL_ASSIGN_COLORS'.  If the
  2076. value of this variable is "yes", then `plotfont -T hpgl' will not be
  2077. restricted to the palette specified in `HPGL_PENS': it will assign
  2078. colors to "logical pens" in the range #1...#31, as needed.  The default
  2079. value is "no" because other than color LaserJet printers and DesignJet
  2080. plotters, not many HP-GL/2 devices allow the assignment of colors to
  2081. logical pens.
  2082.    `plotfont -T tek', which produces output for a Tektronix terminal or
  2083. emulator, checks the `TERM' environment variable.  If the value of
  2084. `TERM' is `xterm', `xterms', or `kterm', it is taken as a sign that the
  2085. current application is running in an X Window System VT100 terminal
  2086. emulator: an `xterm'.  Before drawing graphics, `plotfont -T tek' will
  2087. emit an escape sequence that causes the terminal emulator's auxiliary
  2088. Tektronix window, which is normally hidden, to pop up.  After the
  2089. graphics are drawn, an escape sequence that returns control to the
  2090. original VT100 window will be emitted.  The Tektronix window will
  2091. remain on the screen.
  2092.    If the value of `TERM' is `kermit', `ansi.sys', `ansissys',
  2093. `ansi.sysk', or `ansisysk', it is taken as a sign that the current
  2094. application is running in the VT100 terminal emulator provided by the
  2095. MS-DOS version of `kermit'.  Before drawing graphics, `plotfont -T tek'
  2096. will emit an escape sequence that switches the terminal emulator to
  2097. Tektronix mode.  Also, some of the Tektronix control codes emitted by
  2098. `plotfont -T tek' will be `kermit'-specific.  There will be a limited
  2099. amount of color support, which is not normally the case (the 16
  2100. `ansi.sys' colors will be supported).  After drawing graphics,
  2101. `plotfont -T tek' will emit an escape sequence that returns the
  2102. emulator to VT100 mode.  The key sequence `ALT minus' can be employed
  2103. manually within `kermit' to switch between the two modes.
  2104. File: plotutils.info,  Node: spline,  Next: ode,  Prev: plotfont,  Up: Top
  2105. The `spline' Program
  2106. ********************
  2107. * Menu:
  2108. * spline Examples::         How to use spline
  2109. * Advanced Use of spline::  More sophisticated uses
  2110. * spline Invocation::       Command-line options
  2111. File: plotutils.info,  Node: spline Examples,  Next: Advanced Use of spline,  Prev: spline,  Up: spline
  2112. How to use `spline'
  2113. ===================
  2114.    GNU `spline' is a program for interpolating between the data points
  2115. in one or more datasets.  Each dataset would consist of values for an
  2116. independent variable and a dependent variable, which may be a vector of
  2117. specified fixed length.  When discussing interpolation, we call these
  2118. variables `t' and `y', respectively.  To emphasize: t is a scalar, but
  2119. in general the dependent variable y may be a vector.
  2120.    The simplest case is when there is a single input file, which is in
  2121. ASCII format, and the vector y is one-dimensional.  This is the
  2122. default.  For example, the input file could contain the dataset
  2123.      0.0  0.0
  2124.      1.0  1.0
  2125.      2.0  0.0
  2126. which are the coordinates (t,y) of the data points (0,0), (1,1), and
  2127. (2,0).  Data points do not need to be on different lines, nor do the t
  2128. and y coordinates of a data point need to be on the same line.
  2129. However, there should be no blank lines in the input if it is to be
  2130. viewed as forming a single dataset.  Also, by default the t coordinate
  2131. should be monotonically increasing, so that y may be viewed as a
  2132. function of t.
  2133.    You would construct a spline (the graph of an `interpolating
  2134. function') passing through the points in this dataset by doing
  2135.      spline input_file > output_file
  2136. To produce a Postscript plot of the spline with the `graph' utility,
  2137. you would do
  2138.      spline input_file | graph -T ps > output.ps
  2139. To display a spline on an X Window System display, you could do
  2140.      echo 0 0 1 1 2 0 | spline | graph -T X
  2141. Notice that the last example avoids the use of the input file
  2142. altogether.  `spline' will read from standard input if no files are
  2143. specified on the command line, or if the special file name `-' is
  2144. specified.
  2145.    What exactly does `spline' do?  First, it fits a curve (the graph of
  2146. an interpolating function) through the points in the dataset.  Then it
  2147. splits the interval over which the independent variable t ranges into
  2148. 100 sub-intervals, and computes the y values at each of the 101
  2149. subdivision points.  It then outputs each of the pairs (t, y).  These
  2150. are the coordinates of 101 points that lie along a curve that
  2151. interpolates between the points in the dataset.  If there is more than
  2152. one dataset in the input (separated by blank lines), each dataset is
  2153. interpolated separately.
  2154.    You may use the `-n' option to replace `100' by any other integer.
  2155. You may also use the `-t' option to specify an interpolation interval
  2156. that differs from the default (the interval over which the independent
  2157. variable ranges).  For example, the command
  2158.      echo 0 0 1 1 2 0 | spline -n 20 -t 1.0 1.5 > output_file
  2159. will produce a dataset consisting of 21 (rather than 101) data points,
  2160. with t values spaced regularly between 1.0 and 1.5 (rather than between
  2161. 0.0 and 2.0).  The data points will lie along a curve passing through
  2162. (0,0), (1,1), and (2,0).  This curve will be a parabola.
  2163.    In general, the interpolating function will be a piecewise cubic
  2164. spline.  That is, between each pair of adjacent `knots' (points in the
  2165. input dataset), y will be a cubic function of t.  This function will
  2166. differ, depending on which pair of knots y lies between.  At each knot,
  2167. both the slope and curvature of the cubic pieces to either side will
  2168. match.  In mathematical terms, the interpolating curve will be twice
  2169. continuously differentiable.
  2170.    `spline' supports `adding tension' to the interpolating curve.
  2171. A nonzero value for the tension can be specified with the `-T' option.
  2172. For example, a spline under considerable tension can be computed and
  2173. displayed by doing
  2174.      echo 0 0 1 0 2 0 | spline -T 10 | graph -T X
  2175. As the tension parameter is increased to positive infinity, the spline
  2176. will converge to a polygonal line.  You are meant to think of the spline
  2177. as being drawn taut.  Actually, tension may be negative as well as
  2178. positive.  A spline with negative tension will tend to bow outward,
  2179. in fact to oscillate sinusoidally.  But as the tension decreases to
  2180. negative infinity, the spline, though oscillatory, will again converge
  2181. to a polygonal line.
  2182.    If the tension is positive, its reciprocal will be the maximum range
  2183. of the independent variable t over which the spline will `like to
  2184. curve'.  Increasing the tension far above zero will accordingly force
  2185. the spline to consist of short curved sections, centered on the data
  2186. points, and sections that are almost straight.  It follows that tension
  2187. is a `dimensionful' quantity.  If the tension is nonzero, then when the
  2188. values of the independent variable are multiplied by some common
  2189. positive factor, the tension should be divided by the same factor to
  2190. obtain a scaled version of the original spline.  If the tension is zero
  2191. (the default, or cubic spline case), then the computation of the spline
  2192. will be unaffected by linear scaling of the data.
  2193.    In mathematical terms, a spline under tension will satisfy the
  2194. differential equation y""=sgn(tension)*(tension^2)y" between each
  2195. successive pair of knots.  If the tension equals zero, which is the
  2196. default, the fourth derivative of y with respect to t will equal zero
  2197. at every point.  In this case, y as a function of t will reduce to a
  2198. cubic polynomial between each successive pair of knots.  But if the
  2199. tension is nonzero, y will not be a polynomial function of t.  It may
  2200. be expressed in terms of exponential functions, however.
  2201.    Irrespective of whether or not the spline is under tension, you may
  2202. specify the `-p' option if you wish the spline to be a periodic
  2203. function of t.  This will only work if the y values for the first and
  2204. last points in the dataset are equal.  Otherwise, it would make no
  2205. sense to compute a periodic interpolation.
  2206.    It is sometimes useful to interpolate between data points at the same
  2207. time as they are generated by an auxiliary program.  That is, it is
  2208. useful for `spline' to function as a real-time filter.  `spline' does
  2209. not normally act as a filter, since computing an interpolating curve
  2210. that is as smooth as possible is a global task.  But if the `-f' option
  2211. is specified, `spline' will indeed function as a filter.  A different
  2212. interpolation algorithm (cubic Bessel interpolation, which is local
  2213. rather than global) will be used.  If `-f' is specified, `-p' may not
  2214. be specified.  Also, if `-f' is specified then an interpolation
  2215. interval (a range of t values) must be requested explicitly with the
  2216. `-t' option.
  2217.    Cubic Bessel interpolation is inherently less smooth than the
  2218. construction of a global cubic spline.  If the `-f' option is
  2219. specified, the slope of the spline at each knot will be chosen by
  2220. fitting a parabola through that knot, and the two adjacent knots.  The
  2221. slopes of the two interpolating segments to either side of each interior
  2222. knot will match at that knot, but typically their curvatures will not.
  2223. In mathematical terms, the interpolating curve will be continuously
  2224. differentiable, but in general not twice continuously differentiable.
  2225. This loss of differentiability is the price that is paid for functioning
  2226. as a real-time filter.
  2227. File: plotutils.info,  Node: Advanced Use of spline,  Next: spline Invocation,  Prev: spline Examples,  Up: spline
  2228. Advanced use of `spline'
  2229. ========================
  2230.    The preceding section explains how `spline' can be employed to
  2231. interpolate a function y of a scalar variable t, in the case when y is
  2232. a scalar.  In this section we explain how to perform more sophisticated
  2233. interpolations.  This includes multidimensional interpolations, and
  2234. interpolations that are splinings of curves, rather than of functions.
  2235.    `spline' can handle the case when y is a vector of arbitrary
  2236. specified dimensionality.  The dimension can be specified with the `-d'
  2237. option.  For example, an input file could contain the multidimensional
  2238. dataset
  2239.      0.0  0.0  1.0
  2240.      1.0  1.0  0.0
  2241.      2.0  0.0  1.0
  2242. which are the coordinates (t,y) of the data points (0,0,1), (1,1,0),
  2243. and (2,0,1).  You would construct a spline (the graph of an
  2244. interpolating function) passing through the points in this dataset by
  2245. doing
  2246.      spline -d 2 input_file > output_file
  2247. The option `-d 2' is used because in this example, the dependent
  2248. variable y is a two-dimensional vector.  Each of the components of y
  2249. will be interpolated independently, and the output file will contain
  2250. points that lie along the graph of the resulting interpolating function.
  2251.    When doing multidimensional splining, you may use any of the options
  2252. that apply in the default one-dimensional case.  For example, the `-f'
  2253. option will yield real-time cubic Bessel interpolation.  As in the
  2254. one-dimensional case, if the `-f' option is used then the `-t' option
  2255. must be used as well, to specify an interpolation interval (a range of
  2256. t values).  The `-p' option will yield a periodic spline, i.e., the
  2257. graph of a periodic vector-valued function.  For this, the first and
  2258. last dataset y values must be the same.
  2259.    `spline' can also be used to draw a curve through arbitrarily chosen
  2260. points in the plane, or in general through arbitrarily chosen points in
  2261. d-dimensional space.  This is not the same as splining, at least as the
  2262. term is conventionally defined.  The reason is that `splining' refers
  2263. to construction of a function, rather than the construction of a curve
  2264. that may or may not be the graph of a function.  Not every curve is the
  2265. graph of a function.
  2266.    The following example shows how you may `spline a curve'.  The
  2267. command
  2268.      echo 0 0 1 0 1 1 0 1 | spline -d 2 -a -s | graph -T X
  2269. will construct a curve in the plane through the four points (0,0),
  2270. (1,0), (1,1), and (0,1), and graph it on an X Window System display.
  2271. The `-d 2' option specifies that the dependent variable y is
  2272. two-dimensional.  The `-a' option specifies that t values are missing
  2273. from the input, and should be automatically generated.  By default, the
  2274. first t value is 0, the second is 1, etc.  The `-s' option specifies
  2275. that the t values should be stripped from the output.
  2276.    The same technique may be used to spline a closed curve.  For
  2277. example, doing
  2278.      echo 0 0 1 0 0 1 0 0 | spline -d 2 -a -s -p | graph -T X
  2279. will construct and graph a closed, lozenge-shaped curve through the
  2280. three points (0,0), (1,0), and (0,1).  The construction of a closed
  2281. curve is guaranteed by the `-p' (i.e., `--periodic') option, and by the
  2282. repetition of the initial point (0,0) at the end of the sequence.
  2283.    When splining a curve, whether open or closed, you may wish to
  2284. substitute the `-A' option for the `-a' option.  Like the `-a' option,
  2285. the `-A' option specifies that t values are missing from the input and
  2286. should be automatically generated.  However, the first t value will be
  2287. zero, and the increment from one t value to the next will be the
  2288. distance between the corresponding values of y.  This scheme for
  2289. generating t values, when constructing a curve through a sequence of
  2290. points, is the scheme that is used in the well known FITPACK subroutine
  2291. library.  It is probably the best approach when the distances between
  2292. successive points fluctuate considerably.
  2293.    A curve through a sequence of points in the plane, whether open or
  2294. closed, may cross itself.  Some interesting visual effects can be
  2295. obtained by adding negative tension to such a curve.  For example, doing
  2296.      echo 0 0 1 0 1 1 0 0 | spline -d 2 -a -s -p -T -14 -n 500 | graph -T X
  2297. will construct a closed curve through the three points (0,0), (1,0),
  2298. and (0,1), which is wound into curlicues.  The `-n 500' option is
  2299. included because there are so many windings.  It specifies that 501
  2300. points should be generated, which is enough to draw a smooth curve.
  2301. File: plotutils.info,  Node: spline Invocation,  Prev: Advanced Use of spline,  Up: spline
  2302. `spline' command-line options
  2303. =============================
  2304. The `spline' program will interpolate vector-valued functions of a
  2305. scalar variable t, and curves in d-dimensional space.  The algorithms
  2306. used by `spline' are similar to those discussed in D. Kincaid and
  2307. [E.] W. Cheney, `Numerical Analysis' (2nd ed., Brooks/Cole, 1996),
  2308. section 6.4, and C. de Boor, `A Practical Guide to Splines'
  2309. (Springer-Verlag, 1978), Chapter 4.
  2310.    Input file names may be specified anywhere on the command line.  That
  2311. is, the relative order of font names and command-line options does not
  2312. matter.  If no file names are specified, or the file name `-' is
  2313. specified, the standard input is read.
  2314.    An input file may contain more than a single dataset.  Unless the
  2315. `-a' or `-A' options are used (see below), each dataset is expected to
  2316. consist of a sequence of data points, given as alternating t and y
  2317. values.  t is the scalar independent variable, and y is the
  2318. vector-valued dependent variable.  The dimensionality of y is specified
  2319. with the `-d' option (the default is 1).
  2320.    If the input file is in ASCII format (the default), its datasets are
  2321. separated by blank lines.  An input file may also contain any number of
  2322. comment lines, which must begin with the comment character `#'.
  2323. Comment lines are ignored.  They are not treated as blank, i.e., they do
  2324. not interrupt a dataset in progress.
  2325.    The options to `spline' are listed below.  There are three sorts of
  2326. option:
  2327.   1. Options specifying the type of interpolation to be performed on
  2328.      each dataset.
  2329.   2. Options specifying the input or output format.
  2330.   3. Options requesting information (e.g., `--help').
  2331. Options that take an argument are followed, in parentheses, by the type
  2332. and default value of the argument.
  2333.    The following options specify the type of interpolation to be
  2334. performed on each dataset.
  2335. `--filter'
  2336.      Use a local interpolation algorithm (the cubic Bessel algorithm),
  2337.      so that `spline' can be used as a real-time filter.  The slope of
  2338.      the interpolating curve at each point in a dataset will be chosen
  2339.      by fitting a quadratic function through that point and the two
  2340.      adjacent points in the dataset.  If `-f' is specified then the
  2341.      `-t' option, otherwise optional, must be used as well.  Also, if
  2342.      `-f' is specified then the `-k', `-p', and `-T' options may not be
  2343.      used.
  2344.      If `-f' is *not* specified, then a different (global)
  2345.      interpolation algorithm will be used.
  2346. `-k K'
  2347. `--boundary-condition K'
  2348.      (Float, default 1.0.) Set the boundary condition parameter for each
  2349.      constructed spline to be K.  In each of its components, the spline
  2350.      will satisfy the two boundary conditions y"[0]=ky"[1] and
  2351.      y"[n]=ky"[n-1].  Here y[0] and y[1] signify the values of a
  2352.      specified component of the vector-valued dependent variable y at
  2353.      the first two points of a dataset, and y[n-1] and y[n] the values
  2354.      at the last two points.  Setting K to zero will yield a `natural'
  2355.      spline, i.e., one that has zero curvature at the two ends of the
  2356.      dataset.  The `-k' option may not be used if `-f' or `-p' is
  2357.      specified.
  2358. `-n N'
  2359. `--number-of-intervals N'
  2360.      (Integer, default 100.)  Subdivide the interval over which
  2361.      interpolation occurs into N subintervals.  The number of data
  2362.      points computed, and written to the output, will be n+1.
  2363. `--periodic'
  2364.      Construct a periodic spline.  If this option is specified, the y
  2365.      values for the first and last points in each dataset must be
  2366.      equal.  The `-f' and `-k' options may not be used if `-p' is
  2367.      specified.
  2368. `-T TENSION'
  2369. `--tension TENSION'
  2370.      (Float, default 0.0.) Set the tension in each interpolating spline
  2371.      to be TENSION.  Between each pair of successive points in a
  2372.      dataset, the constructed spline will satisfy the differential
  2373.      equation y""=sgn(tension)*(tension^2)y" in each of its components.
  2374.      If TENSION equals zero, the spline will be piecewise cubic.  As
  2375.      TENSION increases to positive infinity, the spline will converge
  2376.      to a polygonal line.  The `-T' option may not be used if `-f' is
  2377.      specified.
  2378. `-t TMIN TMAX [TSPACING]'
  2379. `--t-limits TMIN TMAX [TSPACING]'
  2380.      For each dataset, set the interval over which interpolation occurs
  2381.      to be the interval between TMIN and TMAX.  If TSPACING is not
  2382.      specified, the interval will be divided into the number of
  2383.      subintervals specified by the `-n' option.  If the `-t' option is
  2384.      not used, the interval over which interpolation occurs will be the
  2385.      entire range of the independent variable in the dataset.  The `-t'
  2386.      option must always be used if the `-f' option is used to request
  2387.      filter-like behavior (see above).
  2388. The following options specify the format of the input file(s) and the
  2389. output file.
  2390. `-d DIMENSION'
  2391. `--y-dimension DIMENSION'
  2392.      (Integer, default 1.)  Set the dimensionality of the dependent
  2393.      variable y in the input and output files to be DIMENSION.
  2394. `-I DATA-FORMAT'
  2395. `--input-format DATA-FORMAT'
  2396.      (Character, default `a'.)  Set the data format for the input
  2397.      file(s) to be DATA-FORMAT.  The possible data formats are as
  2398.      follows.
  2399.     `a'
  2400.           ASCII format.  Each file is a sequence of floating point
  2401.           numbers, interpreted as the t and y coordinates of the
  2402.           successive data points in a dataset.  If y is d-dimensional,
  2403.           there will be d+1 numbers for each point.  The t and y
  2404.           coordinates of a point need not appear on the same line, and
  2405.           points need not appear on different lines.  But if a blank
  2406.           line occurs (i.e., two newlines in succession are seen), it is
  2407.           interpreted as the end of a dataset, and the beginning of the
  2408.           next.
  2409.     `f'
  2410.           Single precision binary format.  Each file is a sequence of
  2411.           floating point numbers, interpreted as the t and y coordinates
  2412.           of the successive data points in a dataset.  If y is
  2413.           d-dimensional, there will be d+1 numbers for each point.
  2414.           Successive datasets are separated by a single occurrence of
  2415.           the quantity `FLT_MAX', which is the largest possible single
  2416.           precision floating point number.  On most machines this is
  2417.           approximately 3.4x10^38.
  2418.     `d'
  2419.           Double precision binary format.  Each file is a sequence of
  2420.           double precision floating point numbers, interpreted as the t
  2421.           and y coordinates of the successive data points in a dataset.
  2422.           If y is d-dimensional, there will be d+1 numbers for each
  2423.           point.  Successive datasets are separated by a single
  2424.           occurrence of the quantity `DBL_MAX', which is the largest
  2425.           possible double precision floating point number.  On most
  2426.           machines this is approximately 1.8x10^308.
  2427.     `i'
  2428.           Integer binary format.  Each file is a sequence of integers,
  2429.           interpreted as the t and y coordinates of the successive data
  2430.           points in a dataset.  If y is d-dimensional, there will be
  2431.           d+1 numbers for each point.  Successive datasets are
  2432.           separated by a single occurrence of the quantity `INT_MAX',
  2433.           which is the largest possible integer.  On most machines this
  2434.           is 2^31-1.
  2435. `-a [STEP_SIZE [LOWER_LIMIT]]'
  2436. `--auto-abscissa [STEP_SIZE [LOWER_LIMIT]]'
  2437.      (Floats, defaults 1.0 and 0.0.)  Automatically generate values for
  2438.      the independent variable (t).  Irrespective of data format (`a',
  2439.      `f', `d', or `i'), this option specifies that the values of the
  2440.      independent variable (t) are missing from the input file: the
  2441.      dataset(s) to be read contain only values of the dependent
  2442.      variable (y), so that if y is d-dimensional, there will be only
  2443.      d numbers for each point.  The increment from each t value to the
  2444.      next will be STEP_SIZE, and the first t value will be LOWER_LIMIT.
  2445. `--auto-dist-abscissa'
  2446.      Automatically generate values for the independent variable (t).
  2447.      This is a variant form of the `-a' option.  The increment from
  2448.      each t value to the next will be the distance between the
  2449.      corresponding y values, and the first t value will be 0.0.  This
  2450.      option is useful when interpolating curves rather than functions
  2451.      (*note Advanced Use of spline::.).
  2452. `-O DATA-FORMAT'
  2453. `--output-format DATA-FORMAT'
  2454.      (Character, default `a'.)  Set the data format for the output file
  2455.      to be DATA-FORMAT.  The interpretation of the DATA-FORMAT argument
  2456.      is the same as for the `-I' option.
  2457. `-P SIGNIFICANT-DIGITS'
  2458. `--precision SIGNIFICANT-DIGITS'
  2459.      (Integer, default 6.)  Set the numerical precision for the t and y
  2460.      values in the output file to be SIGNIFICANT-DIGITS.  This takes
  2461.      effect only if the output file is written in `a' format, i.e., in
  2462.      ASCII.
  2463. `--suppress-abscissa'
  2464.      Omit the independent variable t from the output file; for each
  2465.      point, supply only the dependent variable y.  If y is
  2466.      d-dimensional, there will be only d numbers for each point,
  2467.      not d+1.  This option is useful when interpolating curves rather
  2468.      than functions (*note Advanced Use of spline::.).
  2469. The following options request information.
  2470. `--help'
  2471.      Print a list of command-line options, and then exit.
  2472. `--version'
  2473.      Print the version number of `spline' and the plotting utilities
  2474.      package, and exit.
  2475. File: plotutils.info,  Node: ode,  Next: libplot,  Prev: spline,  Up: Top
  2476. The `ode' Program
  2477. *****************
  2478.    The GNU `ode' utility can produce a numerical solution to the
  2479. initial value problem for many systems of first-order ordinary
  2480. differential equations (ODE's).  `ode' can also be used to solve
  2481. systems of higher-order ODE's, since a simple procedure converts an
  2482. n'th-order equation into n first-order equations.  The output of `ode'
  2483. can easily be piped to `graph', so that one or more solution curves may
  2484. be plotted as they are generated.
  2485.    Three distinct schemes for numerical solution are implemented:
  2486. Runge-Kutta-Fehlberg (the default), Adams-Moulton, and Euler.  The
  2487. Runge-Kutta-Fehlberg and Adams-Moulton schemes are available with
  2488. adaptive stepsize.
  2489. * Menu:
  2490. * Basic Math::                  Ordinary differential equations
  2491. * Simple ode Examples::         Simple examples using ode
  2492. * Additional ode Examples::     Additional examples using ode
  2493. * ode Invocation::              ode command-line options
  2494. * Diagnostics::                 Diagnostic messages
  2495. * Numerical Error::             Numerical error and how to avoid it
  2496. * Running Time::                Time spent running ode
  2497. * Input Language::              The ode input language formally specified
  2498. * ODE Bibliography::            Bibliography on ode and ODE's
  2499. File: plotutils.info,  Node: Basic Math,  Next: Simple ode Examples,  Prev: ode,  Up: ode
  2500. Mathematical basics
  2501. ===================
  2502.    We begin with some standard definitions.  A *differential equation*
  2503. is an equation involving an unknown function and its derivatives.
  2504. A differential equation is *ordinary* if the unknown function depends
  2505. on only one independent variable, often denoted t.  The *order* of the
  2506. differential equation is the order of the highest-order derivative in
  2507. the equation.  One speaks of a family, or *system* of equations when
  2508. more than one equation is involved.  If the equations are dependent on
  2509. one another, they are said to be *coupled*.  A *solution* is any
  2510. function satisfying the equations.  An *initial value problem* is
  2511. present when there exist subsidiary conditions on the unknown function
  2512. and its derivatives, all of which are given at the same value of the
  2513. independent variable.  In principle, such an `initial condition'
  2514. specifies a unique solution.  Questions about the existence and
  2515. uniqueness of a solution, along with further terminology, are discussed
  2516. in any introductory text.  (See Chapter 1 of Birkhoff and Rota's
  2517. `Ordinary Differential Equations'.  For this and other references
  2518. relevant to `ode', see *Note ODE Bibliography::.)
  2519.    In practical problems, the solution of a differential equation is
  2520. usually not expressible in terms of elementary functions.  Hence the
  2521. need for a numerical solution.
  2522.    A numerical scheme for solving an initial value problem produces an
  2523. approximate solution, using only functional evaluations and the
  2524. operations of arithmetic.  `ode' solves first-order initial value
  2525. problems of the form:
  2526.      x' = f(t,x,y,...,z)
  2527.      y' = g(t,x,y,...,z)
  2528.         .
  2529.         .
  2530.         .
  2531.      z' = h(t,x,y,...,z)
  2532. given the initial values for each dependent variable at the initial
  2533. value of the independent variable t, i.e.,
  2534.      x(a) = b
  2535.      y(a) = c
  2536.           .
  2537.           .
  2538.           .
  2539.      z(a) = d
  2540.      t = a
  2541. where a,b,c,...,d are constants.
  2542.    For `ode' to be able to solve such a problem numerically, the
  2543. functions f,g,...,h must be expressed, using the usual operators (+, -,
  2544. *, /, and ^), in terms of certain basic functions that `ode'
  2545. recognizes.  These are the same functions that the plotting program
  2546. `gnuplot' recognizes.  Moreover, each of f,g,...,h must be given
  2547. explicitly.  `ode' cannot deal with a system in which one or more of
  2548. the first derivatives is defined implicitly rather than explicitly.
  2549.    All schemes for numerical solution involve the calculation of an
  2550. approximate solution at discrete values of the independent variable t,
  2551. where the `stepsize' (the difference between any two successive values
  2552. of t, usually denoted h) may be constant or chosen adaptively.
  2553. In general, as the stepsize decreases the solution becomes more
  2554. accurate.  In `ode', the stepsize can be adjusted by the user.
  2555. File: plotutils.info,  Node: Simple ode Examples,  Next: Additional ode Examples,  Prev: Basic Math,  Up: ode
  2556. Simple examples using `ode'
  2557. ===========================
  2558.    The following examples should illustrate the procedure of stating an
  2559. initial value problem and solving it with `ode'.  If these examples are
  2560. too elementary, see *Note Input Language::, for a formal specification
  2561. of the `ode' input language.  There is also a directory containing
  2562. examples of `ode' input, which is distributed along with the GNU
  2563. plotting utilities.  On most systems it is installed as
  2564. `/usr/share/ode' or `/usr/local/share/ode'.
  2565.    Our first example is a simple one, namely
  2566.      y'(t) = y(t)
  2567. with the initial condition
  2568.      y(0) = 1
  2569. The solution to this differential equation is
  2570.      y(t) = e^t.
  2571. In particular
  2572.      y(1) = e^1 = 2.718282
  2573. to seven digits of accuracy.
  2574.    You may obtain this result with the aid of `ode' by typing on the
  2575. command line the sequence of commands
  2576.      ode
  2577.      y' = y
  2578.      y = 1
  2579.      print t, y
  2580.      step 0, 1
  2581. Two columns of numbers will appear.  Each line will show the value of
  2582. the independent variable t, and the value of the variable y, as t is
  2583. `stepped' from 0 to 1.  The last line will be
  2584.      1 2.718282
  2585. as expected.  You may use the `-p' option to change the precision.  If,
  2586. for example, you type `ode -p 10' rather than `ode', you will get ten
  2587. digits of accuracy in the output, rather than seven (the default).
  2588.    After the above output, `ode' will wait for further instructions.
  2589. Entering for example the line
  2590.      step 1, 0
  2591. should yield two more columns of numbers, containing the values of t
  2592. and y that are computed when t is stepped back from 1 to 0.  You could
  2593. type instead
  2594.      step 1, 2
  2595. to increase rather than decrease t.  To exit `ode', you would type a
  2596. line containing only `.', i.e. a single period, and tap `return'.
  2597. `ode' will also exit if it sees an end-of-file indicator in its input
  2598. stream, which you may send from your terminal by typing control-D.
  2599.    Each line of the preceding example should be self-explanatory.
  2600. A `step' statement sets the beginning and the end of an interval over
  2601. which the independent variable (here, t) will range, and causes `ode'
  2602. to set the numerical scheme in motion.  The initial value appearing in
  2603. the first `step' statement (i.e., 0) and the assignment statement
  2604.      y = 1
  2605. are equivalent to the initial condition y(0) = 1.  The statements
  2606. `y' = y' and `y = 1' are very different: `y' = y' defines a way of
  2607. computing the derivative of y, while `y = 1' sets the initial value
  2608. of y.  Whenever a `step' statement is encountered, `ode' tries to step
  2609. the independent variable through the interval it specifies.  Which
  2610. values are to be printed at each step is specified by the most recent
  2611. `print' statement.  For example,
  2612.      print t, y, y'
  2613. would cause the current value of the independent variable t, the
  2614. variable y, and its derivative to be printed at each step.
  2615.    To illustrate `ode''s ability to take its input or the initial part
  2616. of its input from a file, you could prepare a file containing the
  2617. following lines:
  2618.      # an ode to Euler
  2619.      y  = 1
  2620.      y' = y
  2621.      print t, y, y'
  2622. Call this file `euler'.  (The `#' line is a comment line, which may
  2623. appear at any point.  Everything from the `#' to the end of the line on
  2624. which it appears will be ignored.)  To process this file with `ode',
  2625. you could type on your terminal
  2626.      ode -f euler
  2627.      step 0, 1
  2628. These two lines cause `ode' to read the file `euler', and the stepping
  2629. to take place.  You will now get three quantities (t, y, and y')
  2630. printed at each of the values of t between 0 and 1.  At the conclusion
  2631. of the stepping, `ode' will wait for any further commands to be input
  2632. from the terminal.  This example illustrates that
  2633.      ode -f euler
  2634. is not equivalent to
  2635.      ode < euler
  2636. The latter would cause `ode' to take all its input from the file
  2637. `euler', while the former allows subsequent input from the terminal.
  2638. For the latter to produce output, you would need to include a `step'
  2639. line at the end of the file.  You would not need to include a `.' line,
  2640. however.  `.' is used to terminate input only when input is being read
  2641. from a terminal.
  2642.    A second simple example involves the numerical solution of a
  2643. second-order differential equation.  Consider the initial value problem
  2644.      y''(t) = -y(t)
  2645.      y(0) = 0
  2646.      y'(0) = 1
  2647. Its solution would be
  2648.      y(t) = sin(t)
  2649. To solve this problem using `ode', you must express this second-order
  2650. equation as two first-order equations.  Toward this end you would
  2651. introduce a new function, called yp say, of the independent variable t.
  2652. The pair of equations
  2653.      y' = yp
  2654.      yp' = -y
  2655. would be equivalent to the single equation above.  This sort of
  2656. reduction of an n'th order problem to n first order problems is a
  2657. standard technique.
  2658.    To plot the variable y as a function of the variable t, you could
  2659. create a file containing the lines
  2660.      # sine : y''(t) = -y(t), y(0) = 0, y'(0) = 1
  2661.      sine' = cosine
  2662.      cosine' = -sine
  2663.      sine = 0
  2664.      cosine = 1
  2665.      print t, sine
  2666. (y and yp have been renamed sine and cosine, since that is what they
  2667. will be.)  Call this file `sine'.  To display the generated data points
  2668. on an X Window System display as they are generated, you would type
  2669.      ode -f sine | graph -T X -x 0 10 -y -1 1
  2670.      step 0, 2*PI
  2671.      .
  2672. After you type the `ode' line, `graph -T X' will pop up a window, and
  2673. after you type the `step' line, the generated dataset will be drawn
  2674. in it.  The `-x 0 10' and `-y -1 1' options, which set the bounds for
  2675. the two axes, are necessary if you wish to display points in real time:
  2676. as they are generated.  If the axis bounds were not specified on the
  2677. command line, `graph -T X' would wait until all points are read from
  2678. the input before determining the bounds, and drawing the plot.
  2679.    A slight modification of this example, showing how `ode' can
  2680. generate several datasets in succession and plot them on the same graph,
  2681. would be the following.  Suppose that you type on your terminal the
  2682. following lines.
  2683.      ode -f sine | graph -T X -C -x 0 10 -y -1 1
  2684.      step 0, PI
  2685.      step PI, 2*PI
  2686.      step 2*PI, 3*PI
  2687.      .
  2688. Then the sine curve will be traced out in three stages.  Since the
  2689. output from each `step' statement ends with a blank line, `graph -T X'
  2690. will treat each section of the sine curve as a different dataset.  If
  2691. you are using a color display, each of the three sections will be
  2692. plotted in a different color.  This is a feature provided by `graph',
  2693. which normally changes its linemode after each dataset it reads.  If
  2694. you do not like this feature, you may turn it off by using `graph -T X
  2695. -B' instead of `graph -T X'.
  2696.    In the above examples, you could use any of the other variants of
  2697. `graph' instead of `graph -T X'.  For example, you could use `graph -T
  2698. ps' to obtain a plot in encapsulated Postscript format, by typing
  2699.      ode -f sine | graph -T ps > plot.ps
  2700.      step 0, 2*PI
  2701.      .
  2702. You should note that of the six variants of `graph', `graph -T ps',
  2703. `graph -T fig', and `graph -T hpgl' do not produce output in real time,
  2704. even when the axis bounds are specified with the `-x' and `-y' options.
  2705. So if `graph -T ps', `graph -T fig', or `graph -T hpgl' is used, the
  2706. plot will be produced only when input from `ode' is terminated, which
  2707. will occur when you type `.'.
  2708.    In the preceding examples, the derivatives of the dependent variables
  2709. were specified by comparatively simple expressions.  They are allowed to
  2710. be arbitrarily complicated functions of the dependent variables and the
  2711. independent variable.  They may also involve any of the functions that
  2712. are built into `ode'.  `ode' has a fair number of functions built in,
  2713. including abs, sqrt, exp, log, log10, sin, cos, tan, asin, acos, atan,
  2714. sinh, cosh, tanh, asinh, acosh, and atanh.  Less familiar functions
  2715. which are built into it are besj0, besj1, besy0, besy1, erf, erfc,
  2716. inverf, lgamma, gamma, norm, invnorm, ibeta, and igamma.  These have
  2717. the same definitions as in the plotting program `gnuplot'.  (All
  2718. functions take a single argument, except for ibeta, which takes three,
  2719. and igamma, which takes two).  `ode' also knows the meaning of the
  2720. constant `PI', as the above examples show.  The names of the preceding
  2721. functions are reserved, so, e.g., `cos' and `sin' may not be used as
  2722. names for variables.
  2723.    Other than the restriction of avoiding reserved names and keywords,
  2724. the names of variables may be chosen arbitrarily.  Any sequence of
  2725. alphanumeric characters starting with an alphabetic character may be
  2726. used; the first 32 characters are significant.  It is worth noting that
  2727. `ode' identifies the independent variable by the fact that it is (or
  2728. should be) the only variable that has not appeared on the left side of
  2729. a differential equation or an initial value assignment.  If there is
  2730. more than than one such variable then no stepping takes place; instead,
  2731. an error message is printed.  If there is no such variable, a dummy
  2732. independent variable is invented and given the name `(indep)',
  2733. internally.
  2734. File: plotutils.info,  Node: Additional ode Examples,  Next: ode Invocation,  Prev: Simple ode Examples,  Up: ode
  2735. Additional examples using `ode'
  2736. ===============================
  2737.    We explain here how to use some additional features of `ode'.
  2738. However, the discussion below does not cover all of its capabilities.
  2739. For a complete list of command-line options, see *Note ode Invocation::.
  2740.    It is easy to use `ode' to create plots of great beauty.  An example
  2741. would be a plot of a *strange attractor*, namely the Lorenz attractor.
  2742. Suppose that a file named `lorenz' contains the following lines.
  2743.      # The Lorenz model, a system of three coupled ODE's with parameter r.
  2744.      x' = -3*(x-y)
  2745.      y' = -x*z+r*x-y
  2746.      z' = x*y-z
  2747.      
  2748.      r = 26
  2749.      x = 0; y = 1; z = 0
  2750.      
  2751.      print x, y
  2752.      step 0, 200
  2753. Then executing the command
  2754.      ode < lorenz | graph -T X -C -x -10 10 -y -10 10
  2755. would produce a plot of the Lorenz attractor (strictly speaking, a plot
  2756. of one of its two-dimensional projections).  You may produce a
  2757. Postscript plot of the Lorenz attractor, and print it, by doing
  2758. something like
  2759.      ode < lorenz | graph -T ps -x -10 10 -y -10 10 -W 0 | lpr
  2760. The `-W 0' ("zero width") option requests that `graph -T ps' use the
  2761. thinnest line possible, to improve the visual appearance of the plot on
  2762. a printer or other Postscript device.
  2763.    Besides plotting a visually striking object in real time, the Lorenz
  2764. attractor example shows how statements may be separated by semicolons,
  2765. rather than appearing on different lines.  It also shows how to use
  2766. symbolic constants.  In the description read by `ode' the parameter r
  2767. is a variable like x, y, and z.  But unlike them it is not updated
  2768. during stepping, since no formula for its derivative r' is given.
  2769.    Our second example deals with the interactive construction of a
  2770. `phase portrait': a set of solution curves with different initial
  2771. conditions.  Phase portraits are of paramount interest in the
  2772. qualitative theory of differential equations, and also possess
  2773. aesthetic appeal.
  2774.    Since a description read by `ode' may contain any number of `step'
  2775. statements, multiple solution curves may be plotted in a single run.
  2776. The most recent `print' statement will be used with each `step'
  2777. statement.  In practice, a phase portrait would be drawn from a few
  2778. well-chosen solution curves.  Choosing a good set of solution curves
  2779. may require experimentation, which makes interactivity and real-time
  2780. plotting all-important.
  2781.    As an example, consider a so-called Lotka-Volterra predator-prey
  2782. model.  Suppose that in a lake there are two species of fish:
  2783. A (the prey) who live by eating a plentiful supply of plants, and B (the
  2784. predator) who eat A.  Let x(t) be the population of A and y(t) the
  2785. population of B at time t.  A crude model for the interaction of A
  2786. and B is given by the equations
  2787.      x' = x(a-by)
  2788.      y' = y(cx-d)
  2789. where a, b, c, d are positive constants.  To draw a phase portrait for
  2790. this system interactively, you could type
  2791.      ode | graph -T X -C -x 0 5 -y 0 5
  2792.      x' = (a - b*y) * x
  2793.      y' = (c*x - d) * y
  2794.      a = 1; b = 1; c = 1; d = 1;
  2795.      print x, y
  2796.      x = 1; y = 2
  2797.      step 0, 10
  2798.      x = 1; y = 3
  2799.      step 0, 10
  2800.      x = 1; y = 4
  2801.      step 0, 10
  2802.      x = 1; y = 5
  2803.      step 0, 10
  2804.      .
  2805. Four curves will be drawn in succession, one per `step' line.  They
  2806. will be periodic; this periodicity is similar to the fluctuations
  2807. between predator and prey populations that occur in real-world
  2808. ecosystems.  On a color display the curves will appear in different
  2809. colors, since by default, `graph' changes the linemode between
  2810. datasets.  That feature may be turned off by using `graph -T X -B'
  2811. rather than `graph -T X'.
  2812.    It is sometimes useful to use `ode' and `graph' to plot discrete
  2813. points, which are not joined by line segments to form a curve.  Our
  2814. third example illustrates this.  Suppose the file `atwoods' contains
  2815. the lines
  2816.      m = 1
  2817.      M = 1.0625
  2818.      a = 0.5; adot = 0
  2819.      l = 10; ldot = 0
  2820.      
  2821.      ldot' = ( m * l * adot * adot - M * 9.8 + m * 9.8 * cos(a) ) / (m + M)
  2822.      l'    = ldot
  2823.      adot' = (-1/l) * (9.8 * sin(a) +  2 * adot * ldot)
  2824.      a'    = adot
  2825.      
  2826.      print l, ldot
  2827.      step 0, 400
  2828. The first few lines describe the functioning of a so-called swinging
  2829. Atwood's machine.  An ordinary Atwood's machine consists of a taut cord
  2830. draped over a pulley, with a mass attached to the cord at each end.
  2831. Normally, the heavier mass (M) would win against the lighter mass (m),
  2832. and draw it upward.  A swinging Atwood's machine allows the lighter
  2833. mass to swing back and forth as well as move vertically.
  2834.    The `print l, ldot' statement requests that the vertical position
  2835. and vertical velocity of the lighter mass be printed out at each step.
  2836. If you run the command
  2837.      ode < atwoods | graph -T X -x 9 11 -y -1 1 -m 0 -S 1 -X l -Y ldot
  2838. you will obtain a real-time plot.  The `-m 0' option requests that
  2839. successive data points not be joined by line segments, and the `-S 1'
  2840. option requests that plotting symbol #1 (a dot) be plotted at the
  2841. location of each point.  As you will see if you run this command, the
  2842. heavy mass does not win against the lighter mass.  Instead the machine
  2843. oscillates non-periodically.  Since the motion is non-periodic, the
  2844. plot benefits from being drawn as a sequence of unconnected points.
  2845.    We conclude by mentioning a few features of `ode' that may be useful
  2846. when things are not going quite right.  One of them is the `examine'
  2847. statement.  It may be used to discover pertinent information about any
  2848. variable in a system.  For details, see *Note Input Language::.
  2849.    Another useful feature is that the `print' statement may be used to
  2850. print out more than just the value of a variable.  As we have seen, if
  2851. the name of the variable is followed by `'', the derivative of the
  2852. variable will be printed instead.  In a similar way, following the
  2853. variable name with `?', `!', or `~' prints respectively the relative
  2854. single-step error, the absolute single-step error, or the accumulated
  2855. error (not currently implemented).  These quantities are discussed in
  2856. *Note Numerical Error::.
  2857.    The `print' statement may be more complicated than was shown in the
  2858. preceding examples.  Its general structure is
  2859.      print <pr-list> [every <const>] [from <const>]
  2860. The bracket notation `[...]' means that the enclosed statements are
  2861. optional.  Until now we have not mentioned the `every' clause or the
  2862. `from' clause.  The <pr-list> is familiar, however; it is simply a
  2863. comma-separated list of variables.  For example, in the statement
  2864.      print t, y, y' every 5 from 1
  2865. the <pr-list> is <t, y, y'>.  The clauses `every 5' and `from 1'
  2866. specify that printing should take place after every fifth step, and
  2867. that the printing should begin when the independent variable t
  2868. reaches 1.  An `every' clause is useful if you wish to `thin out' the
  2869. output generated by a `step' statement, and a `from' clause is useful
  2870. if you wish to view only the final portion of a solution curve.
  2871. File: plotutils.info,  Node: ode Invocation,  Next: Diagnostics,  Prev: Additional ode Examples,  Up: ode
  2872. `ode' command-line options
  2873. ==========================
  2874. The command-line options to `ode' are listed below.  There are several
  2875. sorts of option:
  2876.   1. Options affecting the way in which input is read.
  2877.   2. Options affecting the format of the output.
  2878.   3. Options affecting the choice of numerical solution scheme, and the
  2879.      error bounds that will be imposed on it.
  2880.   4. Options that request information.
  2881. The following option affects the way input is read.
  2882. `-f FILENAME'
  2883. `--input-file FILENAME'
  2884.      Read input from FILENAME before reading from standard input.
  2885. The following options affect the output format.
  2886. `-p PRECISION'
  2887. `--precision PRECISION'
  2888.      When printing numerical results, use PRECISION significant
  2889.      figures.  If this option is given, all output will be in scientific
  2890.      notation.
  2891. `--title'
  2892.      Print a title line at the head of the output, naming the columns.
  2893.      If this option is given, the default print format will be
  2894.      scientific notation.
  2895. The following options specify the numerical integration scheme.  Only
  2896. one of the three basic option `-R', `-A', and `-E' may be specified.
  2897. The default is `-R' (Runge-Kutta-Fehlberg).
  2898. `-R [STEPSIZE]'
  2899. `--runge-kutta [STEPSIZE]'
  2900.      Use a fifth-order Runge-Kutta-Fehlberg algorithm, with an adaptive
  2901.      stepsize unless a constant stepsize is specified.  When a constant
  2902.      stepsize is specified and no error analysis is requested, then a
  2903.      classical fourth-order Runge-Kutta scheme is used.
  2904. `-A [STEPSIZE]'
  2905. `--adams-moulton [STEPSIZE]'
  2906.      Use a fourth-order Adams-Moulton predictor-corrector scheme, with
  2907.      an adaptive stepsize unless a constant stepsize, STEPSIZE, is
  2908.      specified.  The Runge-Kutta-Fehlberg algorithm is used to get past
  2909.      `bad' points (if any).
  2910. `-E [STEPSIZE]'
  2911. `--euler [STEPSIZE]'
  2912.      Use a `quick and dirty' Euler scheme, with a constant stepsize.
  2913.      The default value of STEPSIZE is 0.1.  Not recommended for serious
  2914.      applications.
  2915. `-h HMIN [HMAX]'
  2916. `--step-size-bound HMIN [HMAX]'
  2917.      Use a lower bound HMIN on the stepsize.  The numerical scheme will
  2918.      not let the stepsize go below HMIN.  The default is to allow the
  2919.      stepsize to shrink to the machine limit, i.e., the minimum nonzero
  2920.      double-precision floating point number.  The optional argument
  2921.      HMAX, if included, specifies a maximum value for the stepsize.
  2922.      It is useful in preventing the numerical routine from skipping
  2923.      quickly over an interesting region.
  2924. The following options set the error bounds on the numerical solution
  2925. scheme.
  2926. `-r RMAX [RMIN]'
  2927. `--relative-error-bound RMAX [RMIN]'
  2928. `-e EMAX [EMIN]'
  2929. `--absolute-error-bound EMAX [EMIN]'
  2930.      The `-r' option sets an upper bound on the relative single-step
  2931.      error.  If the `-r' option is used, the relative single-step error
  2932.      in any dependent variable will never exceed RMAX (the default for
  2933.      which is 10^(-9)).  If this should occur, the solution will be
  2934.      abandoned and an error message will be printed.  If the stepsize
  2935.      is not constant, the stepsize will be decreased `adaptively', so
  2936.      that the upper bound on the single-step error is not violated.
  2937.      Thus, choosing a smaller upper bound on the single-step error will
  2938.      cause smaller stepsizes to be chosen.  A lower bound RMIN may
  2939.      optionally be specified, to suggest when the stepsize should be
  2940.      increased (the default for RMIN is RMAX/1000).  The `-e' option is
  2941.      similar to `-r', but bounds the absolute rather than the relative
  2942.      single-step error.
  2943. `--suppress-error-bound'
  2944.      Suppress the ceiling on single-step error, allowing `ode' to
  2945.      continue even if this ceiling is exceeded.  This may result in
  2946.      large numerical errors.
  2947. Finally, the following options request information.
  2948. `--help'
  2949.      Print a list of command-line options, and then exit.
  2950. `--version'
  2951.      Print the version number of `ode' and the plotting utilities
  2952.      package, and exit.
  2953. File: plotutils.info,  Node: Diagnostics,  Next: Numerical Error,  Prev: ode Invocation,  Up: ode
  2954. Diagnostic messages
  2955. ===================
  2956.    `ode' is always in one of two states:
  2957.    * Reading input.  The input includes a specification of a system of
  2958.      ordinary differential equations, together with instructions for
  2959.      solving it numerically: a `print' line and a `step' line.
  2960.    * Numerically solving a system, and printing the resulting output.
  2961. `ode' moves from the first to the second state after it sees and
  2962. processes a `step' line.  It returns to the first state after the
  2963. generated output has been printed.  Errors may occur in either the
  2964. `reading' state or the `solving' state, and may terminate computations
  2965. or even cause `ode' to exit.  We now explain the possible sorts of
  2966. error.
  2967.    While reading input, `ode' may encounter a syntax error: an
  2968. ungrammatical line that it is unable to parse.  (For a summary of its
  2969. input grammar, see *Note Input Language::.)  If so, it emits the error
  2970. message
  2971.      ode::nnn: syntax error
  2972. where `nnn' is the number of the line containing the error.  When the
  2973. `-f filename' option is used to specify an input file, the error
  2974. message will read
  2975.      ode:filename:nnn: syntax error
  2976. for errors encountered inside the input file.  Subsequently, when `ode'
  2977. begins reading the standard input, line numbers will start over again
  2978. from 1.
  2979.    No effort is made to recover from syntax errors in the input.
  2980. However, there is a meager effort to resynchronize, so that more than
  2981. one syntax error in a file may be found at the same time.
  2982.    It is also possible that a fatal arithmetic exception (such as a
  2983. division by zero, or a floating point overflow) may occur while `ode'
  2984. is reading input.  If such an exception occurs, `ode' will print an
  2985. "Floating point exception" error message and exit.  Arithmetic
  2986. exceptions are machine-dependent.  On some machines, the line
  2987.      y = 1/0
  2988. would induce an arithmetic exception.  Also on some machines (not
  2989. necessarily the same ones), the lines
  2990.      y = 1e100
  2991.      z = y^4
  2992. would induce an arithmetic exception.  That is because on most
  2993. machines, the double precision quantities that `ode' uses internally
  2994. are limited to a maximum size of approximately 1.8x10^308.
  2995.    When `ode' is in the `solving' state, i.e., computing a numerical
  2996. solution, similar arithmetic exceptions may occur.  If so, the solution
  2997. will be interrupted and a message resembling
  2998.      ode: arithmetic exception while calculating y'
  2999. will be printed.  However, `ode' will not exit; the exception will be
  3000. `caught'.  `ode' itself recognizes the following exceptional
  3001. conditions: square root of a negative number, logarithm of a
  3002. non-positive number, and negative number raised to a non-integer power.
  3003. `ode' will catch any of these operations before it is performed, and
  3004. print an error message specifying which illegal operation it has
  3005. encountered.
  3006.      ode: square root of a negative number while calculating y'
  3007. would be a typical error message.
  3008.    If the machine on which `ode' is running supports the `matherr'
  3009. facility for reporting errors in the computation of standard
  3010. mathematical functions, it will be used.  This facility reports domain
  3011. errors and range errors (overflows, underflows, and losses of
  3012. significance) that could occur when evaluating such functions as `log',
  3013. `gamma', etc.; again, before they are performed.  If the `matherr'
  3014. facility is present, the error message will be fairly informative.  For
  3015. example, the error message
  3016.      ode: range error (overflow) in lgamma while calculating y'
  3017. could be generated if the logarithmic gamma function `lgamma' is
  3018. evaluated at a value of its argument that is too large.  The generation
  3019. of any such message, except a message warning of an underflow, will
  3020. cause the numerical solution to be interrupted.
  3021.    There is another sort of error that may occur during numerical
  3022. solution: the condition that an error ceiling, which the user may set
  3023. with the `-r' option or the `-e' option, is exceeded.  This too will
  3024. cause the numerical solution to be abandoned, and `ode' to switch back
  3025. to reading input.
  3026. File: plotutils.info,  Node: Numerical Error,  Next: Running Time,  Prev: Diagnostics,  Up: ode
  3027. Numerical error and how to avoid it
  3028. ===================================
  3029.    This discussion is necessarily incomplete.  Entire books exist on any
  3030. subject mentioned below (e.g., floating point error).  Our goals are
  3031. modest: first, to introduce the basic notions of error analysis as they
  3032. apply to `ode'; second, to steer you around the more obvious pitfalls.
  3033. You should look through a numerical analysis text (e.g., Atkinson's
  3034. `Introduction to Numerical Analysis') before beginning this discussion.
  3035.    We begin with some key definitions.  The error of greatest concern is
  3036. the difference between the actual solution and the numerical
  3037. approximation to the solution; this is termed the *accumulated error*,
  3038. since the error is built up during each numerical step.  Unfortunately,
  3039. an estimate of this error is usually not available without knowledge of
  3040. the actual solution.  There are, however, several more usable notions
  3041. of error.  The *single-step error*, in particular, is the difference
  3042. between the actual solution and the numerical approximation to the
  3043. solution after any single step, assuming the value at the beginning of
  3044. the step is correct.
  3045.    The *relative single-step error* is the single-step error, divided
  3046. by the current value of the numerical approximation to the solution.
  3047. Why not divided by the current value of the solution itself?  The reason
  3048. is that the solution is not exactly known.  When free to choose a
  3049. stepsize, `ode' will do so on the basis of the relative single-step
  3050. error.  By default, it will choose the stepsize so as to maintain an
  3051. accuracy of eight significant digits in each step.  That is, it will
  3052. choose the stepsize so as not to violate an upper bound of 10^(-9) on
  3053. the relative single-step error.  This ceiling may be adjusted with the
  3054. `-r' option.
  3055.    Where does numerical error come from?  There are two sources.  The
  3056. first is the finite precision of machine computation.  All computers
  3057. work with floating point numbers, which are not real numbers, but only
  3058. an approximation to real numbers.  However, all computations performed
  3059. by `ode' are done to double precision, so floating point error tends to
  3060. be relatively small.  You may nonetheless detect the difference between
  3061. real numbers and floating point numbers by experimenting with the `-p
  3062. 17' option, which will print seventeen significant digits.  On most
  3063. machines, that is the precision of a double precision floating point
  3064. number.
  3065.    The second source of numerical error is often called the
  3066. *theoretical truncation error*.  It is the difference between the
  3067. actual solution and the approximate solution due solely to the
  3068. numerical scheme.  At the root of many numerical schemes is an infinite
  3069. series; for ordinary differential equations, it is a Taylor expansion.
  3070. Since the computer cannot compute all the terms in an infinite series,
  3071. a numerical scheme necessarily uses a truncated series; hence the term.
  3072. The single-step error is the sum of the theoretical truncation error
  3073. and the floating point error, though in practice the floating point
  3074. error is seldom included.  The single-step error estimated by `ode'
  3075. consists only of the theoretical truncation error.
  3076.    We say that a numerical scheme is *stable*, when applied to a
  3077. particular initial value problem, if the error accumulated during the
  3078. solution of the problem over a fixed interval decreases as the stepsize
  3079. decreases; at least, over a wide range of step sizes.  With this
  3080. definition both the Runge-Kutta-Fehlberg (`-R') scheme and the
  3081. Adams-Moulton (`-A') scheme are stable (a statement based more on
  3082. experience than on theoretical results) for a wide class of problems.
  3083.    After these introductory remarks, we list some common sources of
  3084. accumulated error and instability in any numerical scheme.  Usually,
  3085. problems with large accumulated error and instability are due to the
  3086. single-step error in the vicinity of a `bad' point being large.
  3087.   1. Singularities.
  3088.      `ode' should not be used to generate a numerical solution on any
  3089.      interval containing a singularity.  That is, `ode' should not be
  3090.      asked to step over points at which the system of differential
  3091.      equations is singular or undefined.
  3092.      You will find the definitions of singular point, regular singular
  3093.      point, and irregular singular point in any good differential
  3094.      equations text.  If you have no favorite, try Birkhoff and Rota's
  3095.      `Ordinary Differential Equations', Chapter 9.  Always locate and
  3096.      classify the singularities of a system, if any, before applying
  3097.      `ode'.
  3098.   2. Ill-posed problems.
  3099.      For `ode' to yield an accurate numerical solution on an interval,
  3100.      the true solution must be defined and well-behaved on that
  3101.      interval.  The solution must also be real.  Whenever any of these
  3102.      conditions is violated, the problem is said to be *ill-posed*.
  3103.      Ill-posedness may occur even if the system of differential
  3104.      equations is well-behaved on the interval.  Strange results, e.g.,
  3105.      the stepsize suddenly shrinking to the machine limit or the
  3106.      solution suddenly blowing up, may indicate ill-posedness.
  3107.      As an example of ill-posedness (in fact, an undefined solution)
  3108.      consider the innocent-looking problem:
  3109.           y' = y^2
  3110.           y(1) = -1
  3111.      The solution on the domain t > 0 is
  3112.           y(t) = -1/t.
  3113.      With this problem you must not compute a numerical solution on any
  3114.      interval that includes t=0.  To convince yourself of this, try to
  3115.      use the `step' statement
  3116.           step 1, -1
  3117.      on this system.  How does `ode' react?
  3118.      As another example of ill-posedness, consider the system
  3119.           y'=1/y
  3120.      which is undefined at y=0.  The general solution is
  3121.           y = +/- (2(t-C))^(1/2),
  3122.      so that if the condition y(2)=2 is imposed, the solution will be
  3123.      (2t)^(1/2).  Clearly, if the domain specified in a `step'
  3124.      statement includes negative values of t, the generated solution
  3125.      will be bogus.
  3126.      In general, when using a constant stepsize you should be careful
  3127.      not to `step over' bad points or bad regions.  When allowed to
  3128.      choose a stepsize adaptively, `ode' will often spot bad points,
  3129.      but not always.
  3130.   3. Critical points.
  3131.      An *autonomous* system is one that does not include the independent
  3132.      variable explicitly on the right-hand side of any differential
  3133.      equation.  A *critical point* for such a system is a point at
  3134.      which all right-hand sides equal zero.  For example, the system
  3135.           y' = 2x
  3136.           x' = 2y
  3137.      has only one critical point, at (x,y) = (0,0).
  3138.      A critical point is sometimes referred to as a *stagnation point*.
  3139.      That is because a system at a critical point will remain there
  3140.      forever, though a system near a critical point may undergo more
  3141.      violent motion.  Under some circumstances, passing near a critical
  3142.      point may give rise to a large accumulated error.
  3143.      As an exercise, solve the system above using `ode', with the
  3144.      initial condition x(0) = y(0) = 0.  The solution should be
  3145.      constant in time.  Now do the same with points near the critical
  3146.      point.  What happens?
  3147.      You should always locate the critical points of a system before
  3148.      attempting a solution with `ode'.  Critical points may be
  3149.      classified (as equilibrium, vortex, unstable, stable, etc.) and
  3150.      this classification may be of use.  To find out more about this,
  3151.      consult any book dealing with the qualitative theory of
  3152.      differential equations (e.g., Birkhoff and Rota's `Ordinary
  3153.      Differential Equations', Chapter 6).
  3154.   4. Unsuitable numerical schemes
  3155.      If the results produced by `ode' are bad in the sense that
  3156.      instability appears to be present, or an unusually small stepsize
  3157.      needs to be chosen needed in order to reduce the single-step error
  3158.      to manageable levels, it may simply be that the numerical scheme
  3159.      being used is not suited to the problem.  For example, `ode'
  3160.      currently has no numerical scheme which handles so-called `stiff'
  3161.      problems very well.
  3162.      As an example, you may wish to examine the stiff problem:
  3163.           y' = -100 + 100t + 1
  3164.           y(0) = 1
  3165.      on the domain [0,1].  The exact solution is
  3166.           y(t) = e^(-100t) + t.
  3167.      It is a useful exercise to solve this problem with `ode' using
  3168.      various numerical schemes, stepsizes, and relative single-step
  3169.      error bounds, and compare the generated solution curves with the
  3170.      actual solution.
  3171.    There are several rough and ready heuristic checks you may perform on
  3172. the accuracy of any numerical solution produced by `ode'.  We discuss
  3173. them in turn.
  3174.   1. Examine the stability of  solution curves: do they converge?
  3175.      That is, check how changing the stepsize affects a solution curve.
  3176.      As the stepsize decreases, the curve should converge.  If it does
  3177.      not, then either the stepsize is not small enough or the numerical
  3178.      scheme is not suited to the problem.  In practice, you would
  3179.      proceed as follows.
  3180.         * If using an adaptive stepsize, superimpose the solution
  3181.           curves for successively smaller bounds on the relative
  3182.           single-step error (obtained with, e.g., `-r 1e-9', `-r
  3183.           1e-11', `-r 1e-13', ...).  If the curves converge then the
  3184.           solution is to all appearances stable, and your accuracy is
  3185.           sufficient.
  3186.         * If employing a constant stepsize, perform a similar analysis
  3187.           by successively halving the stepsize.
  3188.      The following example is one that you may wish to experiment with.
  3189.      Make a file named `qcd' containing:
  3190.           # an equation arising in QCD (quantum chromodynamics)
  3191.           f'   = fp
  3192.           fp'  = -f*g^2
  3193.           g'   = gp
  3194.           gp'  = g*f^2
  3195.           f = 0; fp = -1; g = 1; gp = -1
  3196.           
  3197.           print t, f
  3198.           step 0, 5
  3199.      Next make a file named `stability', containing the lines:
  3200.           : sserr is the bound on the relative single-step error
  3201.           for sserr
  3202.           do
  3203.           ode -r $sserr < qcd
  3204.           done | spline -n 500 | graph -T X -C
  3205.      This is a `shell script', which when run will superimpose numerical
  3206.      solutions with specified bounds on the relative single-step error.
  3207.      To run it, type:
  3208.           sh stability 1 .1 .01 .001
  3209.      and a plot of the solutions with the specified error bounds will be
  3210.      drawn.  The convergence, showing stability, should be quite
  3211.      illuminating.
  3212.   2. Check invariants of the system: are they constant?
  3213.      Many systems have invariant quantities.  For example, if the
  3214.      system is a mathematical model of a `conservative' physical system
  3215.      then the `energy' (a particular function of the dependent
  3216.      variables of the system) should be constant in time.  In general,
  3217.      knowledge about the qualitative behavior of any dependent variable
  3218.      may be used to check the quality of the solution.
  3219.   3. Check a family of solution curves: do they diverge?
  3220.      A rough idea of how error is propagated is obtained by viewing a
  3221.      family of solution curves about the numerical solution in
  3222.      question, obtained by varying the initial conditions.  If they
  3223.      diverge sharply--that is, if two solutions which start out very
  3224.      close nonetheless end up far apart--then the quality of the
  3225.      numerical solution is dubious.  On the other hand, if the curves
  3226.      do not diverge sharply then any error that is present will in all
  3227.      likelihood not increase by more than an order of magnitude or so
  3228.      over the interval.  Problems exhibiting no sharp divergence of
  3229.      neighboring solution curves are sometimes called
  3230.      *well-conditioned*.
  3231. File: plotutils.info,  Node: Running Time,  Next: Input Language,  Prev: Numerical Error,  Up: ode
  3232. Running time
  3233. ============
  3234.    The time required for `ode' to solve numerically a system of
  3235. ordinary differential equations depends on a great many factors.  A few
  3236. of them are: number of equations, complexity of equations (number of
  3237. operators and nature of the operators), and number of steps taken
  3238. (a very complicated function of the difficulty of solution, unless
  3239. constant stepsizes are used).  The most effective way to gauge the time
  3240. required for solution of a system is to clock a short or imprecise run
  3241. of the problem, and reason as follows: the time required to take two
  3242. steps is roughly twice that required for one; and there is a
  3243. relationship between the number of steps required and the relative error
  3244. ceiling chosen.  That relationship depends on the numerical scheme being
  3245. used, the difficulty of solution, and perhaps on the magnitude of the
  3246. error ceiling itself.  A few carefully planned short runs may be used
  3247. to determine this relationship, enabling a long but imprecise run to be
  3248. used as an aid in projecting the cost of a more precise run over the
  3249. same region.  Lastly, if a great deal of data is printed, it is likely
  3250. that more time is spent in printing the results than in computing the
  3251. numerical solution.
  3252. File: plotutils.info,  Node: Input Language,  Next: ODE Bibliography,  Prev: Running Time,  Up: ode
  3253. The `ode' input language formally specified
  3254. ===========================================
  3255.    The following is a formal specification of the grammar for `ode''s
  3256. input language, in Backus-Naur form.  Nonterminal symbols in the
  3257. grammar are enclosed in angle brackets.  Terminal tokens are in all
  3258. capitals.  Bare words and symbols stand for themselves.
  3259.      <program>    ::=        ... empty ...
  3260.                     |  <program> <statement>
  3261.      
  3262.      
  3263.      <statement>  ::=  SEP
  3264.                     |  IDENTIFIER = <const> SEP
  3265.                     |  IDENTIFIER ' = <expression> SEP
  3266.                     |  print <printlist> <optevery> <optfrom> SEP
  3267.                     |  step <const> , <const> , <const> SEP
  3268.                     |  step <const> , <const> SEP
  3269.                     |  examine IDENTIFIER SEP
  3270.      
  3271.      
  3272.      <printlist>  ::=  <printitem>
  3273.                     |  <printlist> , <printitem>
  3274.      
  3275.      
  3276.      <printitem>  ::=  IDENTIFIER
  3277.                     |  IDENTIFIER '
  3278.                     |  IDENTIFIER ?
  3279.                     |  IDENTIFIER !
  3280.                     |  IDENTIFIER ~
  3281.      
  3282.      
  3283.      <optevery>   ::=        ... empty ...
  3284.                     |  every <const>
  3285.      
  3286.      
  3287.      <optfrom>    ::=        ... empty ...
  3288.                     |  from <const>
  3289.      
  3290.      
  3291.      <const>      ::=  <expression>
  3292.      
  3293.      
  3294.      <expression> ::=  ( <expression> )
  3295.                     |  <expression> + <expression>
  3296.                     |  <expression> - <expression>
  3297.                     |  <expression> * <expression>
  3298.                     |  <expression> / <expression>
  3299.                     |  <expression> ^ <expression>
  3300.                     |  FUNCTION ( <expression> )
  3301.                     |  - <expression>
  3302.                     |  NUMBER
  3303.                     |  IDENTIFIER
  3304. Since this grammar is ambiguous, the following table summarizes the
  3305. precedences and associativities of operators within expressions.
  3306. Precedences decrease from top to bottom.
  3307.      Class           Operators    Associativity
  3308.      
  3309.      Exponential         ^            right
  3310.      Multiplicative      * /          left
  3311.      Additive            + -          left
  3312.    As noted in the grammar, there are six types of nontrivial statement.
  3313. We now explain the effects (the `semantics') of each type, in turn.
  3314.   1. IDENTIFIER ' = <expression>
  3315.      This defines a first-order differential equation.  The derivative
  3316.      of IDENTIFIER is specified by <expression>.  If a dynamic variable
  3317.      does not appear on the left side of a statement of this form, its
  3318.      derivative is assumed to be zero.  That is, it is a symbolic
  3319.      constant.
  3320.   2. IDENTIFIER = <const>
  3321.      This sets the value of IDENTIFIER to the current value of
  3322.      <expression>.  Dynamic variables that have not been initialized in
  3323.      this way are set to zero.
  3324.   3. step <const> , <const>
  3325.   4. step <const> , <const> , <const>
  3326.      A `step' statement causes the numerical scheme to be executed.  The
  3327.      first <const> is the initial value of the independent variable.
  3328.      The second is its final value.  The third is a stepsize; if given,
  3329.      it overrides any stepsize that may be specified on the command
  3330.      line.  Usually the stepsize is not specified, and it varies
  3331.      adaptively as the computation proceeds.
  3332.   5. print <printlist> [ every <const> ] [ from <const> ]
  3333.      A `print' statement controls the content and frequency of the
  3334.      numerical output.  <printlist> is a comma-separated list of
  3335.      IDENTIFIERs, where each IDENTIFIER may be followed by `'',
  3336.      denoting the derivative, or `?', denoting the relative single-step
  3337.      error, or `!', denoting the absolute single-step error, or `~',
  3338.      denoting the accumulated error (not currently implemented).  The
  3339.      specified values are printed in the order they are found.  Both the
  3340.      `every' clause and the `from' clause are optional.  If the `every'
  3341.      clause is present, a printing occurs every <const> iterations of
  3342.      the numerical algorithm.  The default is to print on every
  3343.      iteration (i.e. `every 1').  The first and last values are always
  3344.      printed.  If the `from' clause is present, it means to begin
  3345.      printing when the independent variable reaches or exceeds <const>.
  3346.      The default is to begin printing immediately.
  3347.      If no `print' statement has been supplied, then the independent
  3348.      variable and all dependent variables which have differential
  3349.      equations associated with them are printed.  The independent
  3350.      variable is printed first; the dependent variables follow in the
  3351.      order their equations were given.
  3352.   6. examine IDENTIFIER
  3353.      An `examine' statement, when executed, causes a table of
  3354.      interesting information about the named variable to be printed on
  3355.      the standard output.  For example, if the statement `examine y'
  3356.      were encountered after execution of the `ode to Euler' example
  3357.      discussed elsewhere, the output would be:
  3358.           "y" is a dynamic variable
  3359.           value:2.718282
  3360.           prime:2.718282
  3361.           sserr:1.121662e-09
  3362.           aberr:3.245638e-09
  3363.           acerr:0
  3364.            code:  push "y"
  3365.      The phrase `dynamic variable' means that there is a differential
  3366.      equation describing the behavior of y.  The numeric items in the
  3367.      table are:
  3368.     value
  3369.           Current value of the variable.
  3370.     prime
  3371.           Current derivative of the variable.
  3372.     sserr
  3373.           Relative single-step error for the last step taken.
  3374.     aberr
  3375.           Absolute single-step error for the last step taken.
  3376.     acerr
  3377.           Total error accumulated during the most recent `step'
  3378.           statement.  Not currently implemented.
  3379.      The `code' section of the table lists the stack operations required
  3380.      to compute the derivative of y (somewhat reminiscent of a reverse
  3381.      Polish calculator).  This information may be useful in discovering
  3382.      whether the precedences in the differential equation statement
  3383.      were interpreted correctly, or in determining the time or space
  3384.      expense of a particular calculation.  `push "y"' means to load y's
  3385.      value on the stack, which is all that is required to compute its
  3386.      derivative in this case.
  3387.    The grammar for the `ode' input language contains four types of
  3388. terminal token: FUNCTION, IDENTIFIER, NUMBER, and SEP.  They have the
  3389. following meanings.
  3390.   1. FUNCTION
  3391.      One of the words: abs, sqrt, exp, log, ln, log10, sin, cos, tan,
  3392.      asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh, floor,
  3393.      ceil, besj0, besj1, besy0, besy1, erf, erfc, inverf, lgamma,
  3394.      gamma, norm, invnorm, ibeta, igamma.  These are defined to have
  3395.      the same meaning as in the plotting program `gnuplot'.  All
  3396.      functions take a single argument, except for ibeta, which takes
  3397.      three, and igamma, which takes two.  For trigonometric functions,
  3398.      all arguments are expressed in radians.  The atan function is
  3399.      defined to give a value between -PI/2 and PI/2 (inclusive).
  3400.   2. IDENTIFIER
  3401.      A sequence of alphanumeric characters starting with an alphabetic
  3402.      character.  The first 32 characters are significant.  Upper and
  3403.      lower-case letters are distinct.  In identifiers, the underscore
  3404.      character is considered alphabetic.  Function names and keywords
  3405.      may not be used as identifiers, nor may `PI'.
  3406.   3. NUMBER
  3407.      A non-empty sequence of digits possibly containing a decimal point
  3408.      and possibly followed by an exponent.  An exponent is `e' or `E',
  3409.      followed by an (optionally signed) one, two, or three-digit
  3410.      number.  All numbers and all parts of numbers are radix 10.
  3411.      A number may not contain any white space.  The special word `PI' is
  3412.      a number.
  3413.   4. SEP
  3414.      A separator: a semicolon or a (non-escaped) newline.
  3415.    In the `ode' input language, upper and lower-case letters are
  3416. distinct.  Comments begin with the character `#' and continue to the
  3417. end of the line.  Long lines may be continued onto a second line by
  3418. ending the first line with a backslash (`\').  That is because the
  3419. combination backslash-newline is equivalent to a space.
  3420.    Spaces or tabs are required in the input whenever they are needed to
  3421. separate identifiers, numbers, and keywords from one another.  Except as
  3422. separators, they are ignored.
  3423. File: plotutils.info,  Node: ODE Bibliography,  Prev: Input Language,  Up: ode
  3424. Bibliography on `ode' and solving differential equations
  3425. ========================================================
  3426.      K. E. Atkinson, `An Introduction to Numerical Analysis', Wiley,
  3427.      1978.  Chapter 6 contains a discussion of the literature on the
  3428.      numerical solution of ordinary differential equations.
  3429.      G. Birkhoff and G. Rota, `Ordinary Differential Equations', 4th
  3430.      ed., Wiley, 1989.
  3431.      N. B. Tufillaro, T. Abbott, and J. Reilly, `An Experimental
  3432.      Approach to Nonlinear Dynamics and Chaos', Addison-Wesley, 1992.
  3433.      Appendix C discusses an earlier version of `ode'.
  3434.      N. B. Tufillaro, E. F. Redish, and J. S. Risley, "`ode':
  3435.      A numerical simulation of ordinary differential equations," pp.
  3436.      480-481 in `Proceedings of the Conference on Computers in Physics
  3437.      Instruction', Addison-Wesley, 1990.
  3438. File: plotutils.info,  Node: libplot,  Next: Appendices,  Prev: ode,  Up: Top
  3439. `libplot', a Function Library
  3440. *****************************
  3441. * Menu:
  3442. * libplot Overview::    Programming with libplot: An overview
  3443. * C Programming::       C programming with libplot
  3444. * Functions::           A list of functions contained in libplot
  3445. * Driver Parameters::   Device driver parameters
  3446. File: plotutils.info,  Node: libplot Overview,  Next: C Programming,  Prev: libplot,  Up: libplot
  3447. Programming with `libplot': An overview
  3448. =======================================
  3449.    GNU `libplot' is a library of functions for drawing two-dimensional
  3450. vector graphics.  It can produce smooth, double-buffered animations for
  3451. the X Window System, and graphical output in many different file
  3452. formats.  It is `device-independent' in the sense that its API
  3453. (application programming interface) is to a large extent independent of
  3454. the display type or output format.
  3455.    The graphical objects which `libplot' can draw include paths,
  3456. circles and ellipses, points, markers, and `adjusted labels' (justified
  3457. text strings).  A *path* is a sequence of line segments, circular arcs,
  3458. and/or elliptic arcs.  Paths may be open or closed.  User-specified
  3459. filling of paths, circles, and ellipses is supported (fill color,
  3460. as well as pen color, may be specified).  There is support for
  3461. maintaining a Postscript-style stack of graphics contexts, i.e.,
  3462. a stack of drawing attribute sets.  User-specifiable attributes other
  3463. than pen color and fill color include path-related attributes such as
  3464. line type and line width, and text-related attributes such as font
  3465. name, font size, and text angle.
  3466.    The fundamental abstraction provided by `libplot' is that of a
  3467. *Plotter*.  A Plotter is an object with an interface for the drawing of
  3468. vector graphics which is similar to the interface provided by a
  3469. traditional pen plotter.  There are many types of Plotter, which differ
  3470. in the display type they produce output for.  Any number of Plotters,
  3471. of the same or different types, may exist simultaneously in an
  3472. application.
  3473.    The drawing operations supported by Plotters of different types are
  3474. identical, in agreement with the principle of device independence.
  3475. So a graphics application that is linked with `libplot' may easily be
  3476. written so as to produce output for any or all of the supported output
  3477. formats.
  3478.    The following are the currently supported types of Plotter.
  3479.    * X Plotters.  An X Plotter, when opened, pops up a window on an
  3480.      X Window System display and draws graphics in it.  The window will
  3481.      be `spun off' when the Plotter is closed; if it is subsequently
  3482.      reopened, a new window will be popped up.  A spun-off window will
  3483.      remain on the screen but will vanish if you type `q' or click your
  3484.      mouse in it.  Future releases may permit X Plotters, when
  3485.      reopened, to reuse an existing window.
  3486.    * X Drawable Plotters.  An X Drawable Plotter draws graphics in one
  3487.      or two specified drawables associated with an X Window System
  3488.      display.  A `drawable' is either a window or a pixmap.  The
  3489.      drawables must be passed to the Plotter as parameters.  (*Note
  3490.      Driver Parameters::.)
  3491.    * Postscript Plotters.  A Postscript Plotter produces Postscript
  3492.      output and directs it to a file or other specified output stream.
  3493.      If only a single page of graphics is drawn on the Plotter then its
  3494.      output is in EPS (encapsulated Postscript) format, so it may be
  3495.      included in another document.  It may also be edited with the
  3496.      `idraw' drawing editor.
  3497.    * Fig Plotters.  A Fig Plotter produces output in Fig format and
  3498.      directs it to a file or other specified output stream.  The output
  3499.      may be edited with the `xfig' drawing editor.  The `xfig' editor
  3500.      will export drawings in various other formats for inclusion in
  3501.      documents.
  3502.    * HP-GL Plotters.  An HP-GL Plotter produces output in the
  3503.      Hewlett-Packard Graphics Language (by default, in HP-GL/2), and
  3504.      directs it to a file or other specified output stream.  The output
  3505.      may be sent to a Hewlett-Packard LaserJet printer or plotter, or
  3506.      included in another document.
  3507.    * Tektronix Plotters.  A Tektronix Plotter produces output in
  3508.      Tektronix 4014 format and directs it to a file or other specified
  3509.      output stream.  The output may be displayed on any Tektronix 4014
  3510.      emulator.  Such an emulator is built into `xterm', the X Window
  3511.      System terminal emulation program.  The MS-DOS version of `kermit'
  3512.      also includes such an emulator.
  3513.    * Metafile Plotters.  A Metafile Plotter produces output in GNU
  3514.      metafile format and directs it to a file or other specified output
  3515.      stream.  This format is an extended version of the `plot(5)'
  3516.      format found on some other operating systems.  (*Note
  3517.      Metafiles::.)  It may be translated to other formats by an
  3518.      invocation of GNU `plot'.  (*Note plot::.)
  3519.    A distinction among these types of Plotter is that all except X and
  3520. X Drawable Plotters write graphics to a file or other output stream.  An
  3521. X Plotter pops up its own windows, and an X Drawable Plotter draws
  3522. graphics in one or two X drawables.
  3523.    Another distinction is that X, X Drawable, Tektronix and Metafile
  3524. Plotters are real-time.  This means that they draw graphics or write to
  3525. an output stream as the drawing operations are invoked on them.
  3526. Postscript, Fig and HP-GL Plotters are not real-time, since their output
  3527. streams can only be emitted after all functions have been called.  For a
  3528. Postscript Plotter this is because a `bounding box' line must be placed
  3529. at the head of the output file.  For a Fig Plotter it is because color
  3530. definitions must be placed at the head of the output file.
  3531.    The most important operations supported by any Plotter are `openpl'
  3532. and `closepl', which open and close it.  Graphics may be drawn, and
  3533. drawing attributes set, only within an `openpl'...`closepl' pair.  The
  3534. graphics produced within each `openpl'...`closepl' pair constitute a
  3535. `page'.  In principle, any Plotter may be opened and closed arbitrarily
  3536. many times.  An X Plotter displays each page in a separate X window,
  3537. and an HP-GL Plotter renders each page as a separate physical page.
  3538. X Drawable Plotters and Tektronix Plotters manipulate a single drawable
  3539. or display, on which pages are displayed in succession.  Plotters that
  3540. do not draw in real time (Postscript, Fig, and HP-GL Plotters) may wait
  3541. until their existence comes to an end (i.e., until they are deleted)
  3542. before outputting their pages of graphics.
  3543.    In the current release of `libplot', Postscript Plotters delay
  3544. outputting graphics in this way, but HP-GL Plotters output each page of
  3545. graphics individually, i.e., when `closepl' is invoked.  Fig Plotters
  3546. are similar, but output at most one page of graphics.  That is because
  3547. Fig format currently supports only a single page.  On account of this
  3548. potential problem with Fig Plotters, all Plotters support an additional
  3549. operation: `outfile'.  The output stream for a Plotter, if it has one,
  3550. may be altered by invoking `outfile' on it.  `outfile' may only be
  3551. invoked outside an `openpl'...`closepl' pair.  By using `outfile', a
  3552. programmer may produce multipage graphics output from Fig Plotters by
  3553. directing output to a sequence of output streams, one per page.  The use
  3554. of `outfile' in other contexts is strongly deprecated.
  3555.    There are several other basic operations which any Plotter supports.
  3556. The `graphics display' drawn in by a Plotter is a square or rectangular
  3557. region on a display device.  But when using any Plotter to draw
  3558. graphics, a user will specify the coordinates of graphical objects in
  3559. device-independent `user coordinates', rather than in device
  3560. coordinates.  A Plotter relates the user coordinate system to the
  3561. device coordinate system by performing an affine transformation, which
  3562. must be specified by the user.
  3563.    Immediately after invoking `openpl' to open a Plotter, an
  3564. application should invoke the `space' operation to initialize this
  3565. affine transformation.  This invocation specifies the rectangular region
  3566. (in user coordinates) that will be mapped by the Plotter to the graphics
  3567. display.  The affine transformation may be updated at any later time by
  3568. invoking `space' again, or by invoking `fconcat'.  The `fconcat'
  3569. operation will `concatenate' (i.e., compose) the current affine
  3570. transformation transformation with any specified affine map.  This sort
  3571. of concatenation is a capability familiar from, e.g., Postscript.
  3572.    Each Plotter maintains a Postscript-style stack of graphics contexts.
  3573. This makes possible the rapid, efficient drawing of complicated pages of
  3574. graphics.  A graphics context includes the current affine
  3575. transformation from the user coordinate system to the device coordinate
  3576. system.  It also includes such modal drawing attributes as graphics
  3577. cursor position, linemode, line width, pen and fill colors, and the
  3578. font used for drawing text.  The state of any uncompleted path (if any)
  3579. is included as well, since paths may be drawn incrementally, one
  3580. portion (line segment or arc) at a time.  The current graphics context
  3581. is pushed onto the stack by calling `savestate', and popped off by
  3582. calling `restorestate'.
  3583.    To permit vector graphics animation, any page of graphics may be
  3584. split into `frames'.  A frame is ended, and a new frame is begun, by
  3585. invoking the `erase' operation.  On a Plotter that does real-time
  3586. plotting (i.e., an X, X Drawable, Tektronix, or Metafile Plotter), this
  3587. erases all plotted objects from the graphics display, allowing a new
  3588. frame to be drawn.  Displaying a sequence of frames in succession
  3589. creates the illusion of smooth animation.
  3590.    On a Plotter that does not do real-time plotting (i.e., a
  3591. Postscript, Fig or HP-GL Plotter), invoking `erase' deletes all plotted
  3592. objects from an internal buffer.  For this reason, Plotters that do not
  3593. do real-time plotting will display only the last frame of any
  3594. multiframe page.
  3595. File: plotutils.info,  Node: C Programming,  Next: Functions,  Prev: libplot Overview,  Up: libplot
  3596. C Programming with `libplot'
  3597. ============================
  3598. * Menu:
  3599. * The C API::                   The C application programming interface
  3600. * C Compiling and Linking::     C compiling and linking
  3601. * Sample C Drawings::           Sample drawings in C
  3602. * Sample C Animations::         Sample animations in C
  3603. * X Programming::        Advanced X Window System programming
  3604. File: plotutils.info,  Node: The C API,  Next: C Compiling and Linking,  Prev: C Programming,  Up: C Programming
  3605. The C application programming interface
  3606. ---------------------------------------
  3607.    `libplot' has bindings for several programming languages.
  3608. Regardless of which language binding is used, the concepts behind
  3609. `libplot' (Plotters, and a fixed set of operations that can be applied
  3610. to any Plotter) remain the same.  However, the ways in which Plotters
  3611. are manipulated (created, selected for use, and deleted) may differ
  3612. between bindings.
  3613.    If you are writing an application in C that will use `libplot' to
  3614. draw vector graphics, the first thing you need to know is how, in the
  3615. C binding, Plotters are manipulated.  There are four functions for
  3616. this: `newpl', `selectpl', `deletepl', and the parameter-setting
  3617. function `parampl'.
  3618.    The `newpl' function will create a Plotter of specified type.  Its
  3619. first argument may be "X", "Xdrawable", "ps", "fig", "hpgl", "tek", or
  3620. "meta".  It returns an integer (a "handle") that may be used to refer
  3621. to the Plotter.  Before using a Plotter that you have created (i.e.,
  3622. before invoking any of the `libplot' operations on it), you must select
  3623. the Plotter for use by calling `selectpl'.  Only one Plotter may be
  3624. selected at a time, but by calling `selectpl' you may switch from
  3625. Plotter to Plotter at any time, even when the selected Plotter is open.
  3626. A Plotter that is not currently selected can be deleted, and its
  3627. storage freed, by calling `deletepl'.
  3628.    Strictly speaking, you do not need to call `newpl', `selectpl', or
  3629. `deletepl' in order to draw graphics.  That is because at startup, a
  3630. single Metafile Plotter that writes to standard output (with
  3631. handle `0') is automatically created and selected.  The presence of
  3632. this default Plotter is for compatibility with pre-GNU versions of
  3633. `libplot'.  Of course, you may not wish to obtain output in metafile
  3634. format, and you may not wish to write to standard output.
  3635.    You should get into the habit of calling `deletepl' whenever you are
  3636. finished using a Plotter.  In general, Plotters that do not plot
  3637. graphics in real time (Postscript Plotters in particular) write out
  3638. graphics only when the plot is finished, and `deletepl' is called.
  3639.    The following table summarizes the action of the four functions in
  3640. the C binding that are used for Plotter manipulation.
  3641. int newpl (const char *TYPE, FILE *IN, FILE *OUT, FILE *ERR);
  3642.      newpl creates a Plotter of type TYPE, where TYPE may be "X",
  3643.      "Xdrawable", "ps", "fig", "hpgl", "tek", or "meta".  The Plotter
  3644.      will have input stream IN, output stream OUT, and error stream
  3645.      ERR.  Currently, all Plotters are write-only and IN is ignored.
  3646.      X Plotters and X Drawable Plotters write graphics to an X Window
  3647.      System display rather than to an output stream, so if TYPE is "X"
  3648.      or "Xdrawable" then OUT is ignored as well.  Error messages
  3649.      (if any) are written to the stream ERR, unless ERR is NULL.  The
  3650.      return value from newpl is a `handle': a nonnegative integer by
  3651.      which the newly created Plotter is referred to.  A negative return
  3652.      value indicates the Plotter could not be created.
  3653. int selectpl (int HANDLE);
  3654.      selectpl selects a Plotter, referred to by its handle, for use.  If
  3655.      any of the basic `libplot' operations is subsequently invoked, it
  3656.      will be applied to the selected Plotter.  Only one Plotter may be
  3657.      selected at a time.  A negative return value indicates the Plotter
  3658.      could not be selected.
  3659.      At startup, a single Metafile Plotter that writes to standard
  3660.      output (with handle `0') is automatically created and selected.
  3661. int deletepl (int HANDLE);
  3662.      deletepl deletes a Plotter, referred to by its handle.  The Plotter
  3663.      must not be selected at the time it is deleted.  A negative return
  3664.      value indicates the Plotter could not be deleted.
  3665. int parampl (const char *PARAMETER, void *VALUE);
  3666.      parampl sets the value of the device driver parameter PARAMETER to
  3667.      VALUE.  Device driver parameters are used for setting Plotter
  3668.      options.  The parameter values in effect at the time any Plotter
  3669.      is created are copied into it.  For most parameters, VALUE should
  3670.      be a `char *', i.e., a string.  Unrecognized parameters are
  3671.      ignored.  For a list of the recognized parameters and their
  3672.      meaning, see *Note Driver Parameters::.
  3673.    Up to now we have not discussed the fourth function, `parampl'.
  3674. Even though the Plotter interface is largely Plotter-independent, it is
  3675. useful to be able to specify certain aspects of a Plotter's behavior at
  3676. the time it is created.  Plotter behavior is captured by a manageable
  3677. number of parameters, which we call *device driver parameters*.
  3678. A value for any parameter can be specified by calling `parampl'.  This
  3679. function does not operate on any particular Plotter: it belongs to the
  3680. C binding as a whole.  The parameter values used by any Plotter are
  3681. constant over the lifetime of the Plotter, and are those that were in
  3682. effect when the Plotter was created.
  3683.    Actually, a slightly more sophisticated rule applies.  If at Plotter
  3684. creation time a parameter is set, the value specified by the most recent
  3685. call to `parampl' will be the value used by the Plotter.  If at Plotter
  3686. creation time a parameter is *not* set, its default value will be used,
  3687. unless there is an environment variable of the same name, in which case
  3688. the value of that environment variable will be used.  This rule
  3689. increases run-time flexibility: an application programmer may allow
  3690. non-critical driver parameters to be specified by the user via
  3691. environment variables.  Once set, a parameter may be unset by the
  3692. programmer by calling `parampl' with a value argument of NULL.  This
  3693. further increases flexibility.
  3694. File: plotutils.info,  Node: C Compiling and Linking,  Next: Sample C Drawings,  Prev: The C API,  Up: C Programming
  3695. C compiling and linking
  3696. -----------------------
  3697.    The source code for a graphics application written in C, if it is to
  3698. use `libplot', must contain the lines
  3699.      #include <stdio.h>
  3700.      #include <plot.h>
  3701. The header file `plot.h' is distributed with `libplot', and should have
  3702. been installed on your system where your C compiler will find it.
  3703. It contains prototypes for each of the functions in `libplot' and some
  3704. miscellaneous definitions.  It may be used with C++ programs as well as
  3705. C programs.
  3706.    To link your application with `libplot', you would use the
  3707. appropriate `-l' option(s) on the command line when compiling it.  You
  3708. would use
  3709.      -lplot -lXaw -lXmu -lXt -lXext -lX11 -lm
  3710. or, in recent versions of the X Window System,
  3711.      -lplot -lXaw -lXmu -lXt -lSM -lICE -lXext -lX11 -lm
  3712. (Alternatively, you may need to use `-lplot -lXm -lXt -lXext -lX11
  3713. -lm', `-lplot -lXm -lXt -lXext -lX11 -lm -lc -lgen', or `-lplot -lXm
  3714. -lXt -lXext -lX11 -lm -lc -lPW', on systems that provide Motif widgets
  3715. instead of Athena widgets.  In recent versions of the X Window System,
  3716. you may need to insert `-lXp' and `-lSM -lICE' also.)
  3717.    On most systems `libplot' is installed as a DLL (dynamically linked
  3718. library, or `shared' library).  This means that the linking with your
  3719. application will take place at run time rather than compile time.  The
  3720. environment variable `LD_LIBRARY_PATH' lists the directories which will
  3721. be searched for DLL's at run time.  For your application to be
  3722. executable, this environment variable should include the directory in
  3723. which `libplot' is stored.
  3724. File: plotutils.info,  Node: Sample C Drawings,  Next: Sample C Animations,  Prev: C Compiling and Linking,  Up: C Programming
  3725. Sample drawings in C
  3726. --------------------
  3727.    The following is a sample application, written in C, that invokes
  3728. `libplot' operations to draw vector graphics.  It draws an intricate
  3729. and beautiful path (Bill Gosper's "C" curve, discussed as Item #135 in
  3730. `HAKMEM', MIT Artificial Intelligence Laboratory Memo #239, 1972).
  3731. As the numeric constant `MAXORDER' (here equal to 12) is increased, the
  3732. path will take on the shape of a curly letter "C", which is the
  3733. envelope of a myriad of epicyclic octagons.
  3734.      #include <stdio.h>
  3735.      #include <plot.h>
  3736.      #define MAXORDER 12
  3737.      
  3738.      void draw_c_curve (double dx, double dy, int order)
  3739.      {
  3740.        if (order >= MAXORDER)
  3741.          fcontrel (dx, dy);        /* continue path along (dx, dy) */
  3742.        else
  3743.          {
  3744.            draw_c_curve (0.5 * (dx - dy), 0.5 * (dx + dy), order + 1);
  3745.            draw_c_curve (0.5 * (dx + dy), 0.5 * (dy - dx), order + 1);
  3746.          }
  3747.      }
  3748.      
  3749.      int main ()
  3750.      {
  3751.        int handle;
  3752.      
  3753.        /* set a Plotter parameter */
  3754.        parampl ("PAGESIZE", "letter");
  3755.      
  3756.        /* create a Postscript Plotter that writes to standard output */
  3757.        if ((handle = newpl ("ps", stdin, stdout, stderr)) < 0)
  3758.          {
  3759.            fprintf (stderr, "Couldn't create Plotter\n");
  3760.            return 1;
  3761.          }
  3762.        selectpl (handle);          /* select the Plotter for use */
  3763.      
  3764.        if (openpl () < 0)          /* open Plotter */
  3765.          {
  3766.            fprintf (stderr, "Couldn't open Plotter\n");
  3767.            return 1;
  3768.          }
  3769.        fspace (0.0, 0.0, 1000.0, 1000.0); /* specify user coordinate system*/
  3770.        flinewidth (0.25);          /* width of lines in user coordinates */
  3771.        pencolorname ("red");       /* path will be drawn in red */
  3772.        erase ();                   /* erase Plotter's graphics display */
  3773.        fmove (600.0, 300.0);       /* position the graphics cursor */
  3774.        draw_c_curve (0.0, 400.0, 0);
  3775.        if (closepl () < 0)         /* close Plotter */
  3776.          {
  3777.            fprintf (stderr, "Couldn't close Plotter\n");
  3778.            return 1;
  3779.          }
  3780.      
  3781.        selectpl (0);               /* select default Plotter */
  3782.        if (deletepl (handle) < 0)  /* delete Plotter we used */
  3783.          {
  3784.            fprintf (stderr, "Couldn't delete Plotter\n");
  3785.            return 1;
  3786.          }
  3787.        return 0;
  3788.      }
  3789.    As you can see, this application begins by calling the `newpl'
  3790. function to create a Postscript Plotter.  The Postscript Plotter will
  3791. produce output for a US letter-sized page, though any other standard
  3792. page size, e.g., "a4", could be substituted.  This would be arranged by
  3793. altering the call to `parampl'.  The `PAGESIZE' parameter is one of
  3794. several Plotter parameters that an application programmer may set by
  3795. calling `parampl'.  For a complete list, see *Note Driver Parameters::.
  3796.    After the Plotter is created, the application selects it for use,
  3797. opens it, and draws the "C" curve recursively.  The drawing of the
  3798. curve is accomplished by invoking `fmove' on the Plotter to position
  3799. the graphics cursor, and then calling `draw_c_curve'.  This subroutine
  3800. repeatedly invokes `fcontrel'.  The `fcontrel' operation continues a
  3801. path by adding a line segment to it.  The endpoint of each line segment
  3802. is specified in relative coordinates, i.e., as an offset from the
  3803. previous point.  After the "C" curve is drawn, the Plotter is closed.
  3804. A Postscript file is written to standard output when `deletepl' is
  3805. called to delete the Plotter.
  3806.    Specifying "fig", "hpgl", "tek", or "meta" as the first argument in
  3807. the call to `newpl', instead of "ps", would yield a Plotter that would
  3808. write graphics to standard output in the specified format, instead of
  3809. Postscript.  The `PAGESIZE' parameter is relevant to the first two of
  3810. these output formats, but is ignored for the latter two.  Specifying
  3811. "meta" as the Plotter type may be useful if you wish to avoid
  3812. recompilation for different output devices.  Metafile output may be
  3813. piped to the `plot' utility and converted to any other supported output
  3814. format, or displayed in an X window.  *Note plot::.
  3815.    If "X" were specified as the first argument of `newpl', the curve
  3816. would be drawn in a popped-up X window, and the output stream argument
  3817. would be ignored.  Which X Window System display the window would
  3818. pop up on would be determined by the `DISPLAY' parameter, or if that
  3819. parameter were not set, by the `DISPLAY' environment variable.  The
  3820. size of the X window would be determined by the `BITMAPSIZE' parameter,
  3821. or if that parameter were not set, by the `BITMAPSIZE' environment
  3822. variable.  The default value is "570x570".
  3823.    You could also specify "Xdrawable" as the Plotter type.  For you to
  3824. make this work, you would need to know a bit about X Window System
  3825. programming.  You would need to create at least one X drawable (i.e.,
  3826. window or a pixmap), and by invoking the `parampl' function before
  3827. `newpl' is called, set it as the value of the parameter
  3828. `XDRAWABLE_DRAWABLE1' or `XDRAWABLE_DRAWABLE2'.  For other parameters
  3829. that affect X Drawable Plotters, see *Note Driver Parameters::.
  3830.    The following is another sample application, written in C, that
  3831. invokes `libplot' operations to draw vector graphics.  It draws a
  3832. spiral consisting of elliptically boxed text strings, each of which
  3833. reads "GNU libplot!".  This figure will be sent to standard output in
  3834. Postscript format.
  3835.      #include <stdio.h>
  3836.      #include <plot.h>
  3837.      #include <math.h>
  3838.      #define SIZE 100.0   /* nominal size of user coordinate frame */
  3839.      #define EXPAND 2.2   /* expansion factor for elliptical box */
  3840.      
  3841.      void draw_boxed_string (char *s, double size, double angle)
  3842.      {
  3843.        double true_size, width;
  3844.      
  3845.        ftextangle (angle);            /* text inclination angle (degrees) */
  3846.        true_size = ffontsize (size);  /* choose font size */
  3847.        width = flabelwidth (s);       /* compute width of text string */
  3848.        fellipserel (0.0, 0.0,         /* draw surrounding ellipse */
  3849.                     EXPAND * 0.5 * width, EXPAND * 0.5 * true_size, angle);
  3850.        alabel ('c', 'c', s);          /* draw centered text string */
  3851.      }
  3852.      
  3853.      int main()
  3854.      {
  3855.        int handle, i;
  3856.      
  3857.        /* set a Plotter parameter */
  3858.        parampl ("PAGESIZE", "letter");
  3859.      
  3860.        /* create a Postscript Plotter that writes to standard output */
  3861.        if ((handle = newpl ("ps", stdin, stdout, stderr)) < 0)
  3862.          {
  3863.            fprintf (stderr, "Couldn't create Plotter\n");
  3864.            return 1;
  3865.          }
  3866.        selectpl (handle);            /* select the Plotter for use */
  3867.      
  3868.        if (openpl () < 0)            /* open Plotter */
  3869.          {
  3870.            fprintf (stderr, "Couldn't open Plotter\n");
  3871.            return 1;
  3872.          }
  3873.        fspace (-(SIZE), -(SIZE), SIZE, SIZE); /* specify user coor system */
  3874.        pencolorname ("blue");        /* pen color will be blue */
  3875.        fillcolorname ("white");
  3876.        filltype (1);                 /* ellipses will be filled with white */
  3877.        fontname ("NewCenturySchlbk-Roman");  /* choose a Postscript font */
  3878.      
  3879.        for (i = 80; i > 1; i--)      /* loop through angles */
  3880.          {
  3881.            double theta, radius;
  3882.      
  3883.            theta = 0.5 * (double)i;  /* theta is in radians */
  3884.            radius = SIZE / pow (theta, 0.35);  /* this yields a spiral */
  3885.            fmove (radius * cos (theta), radius * sin (theta));
  3886.            draw_boxed_string ("GNU libplot!", 0.04 * radius,
  3887.                                (180.0 * theta / M_PI) - 90.0);
  3888.          }
  3889.      
  3890.        if (closepl () < 0)           /* close Plotter */
  3891.          {
  3892.            fprintf (stderr, "Couldn't close Plotter\n");
  3893.            return 1;
  3894.          }
  3895.        selectpl (0);
  3896.        if (deletepl (handle) < 0)    /* delete Plotter we used */
  3897.          {
  3898.            fprintf (stderr, "Couldn't delete Plotter\n");
  3899.            return 1;
  3900.          }
  3901.        return 0;
  3902.      }
  3903.    This example shows what is involved in plotting a text string or text
  3904. strings.  First, the desired font must be retrieved.  A font is fully
  3905. specified by invoking `fontname', `fontsize', and `textangle', or their
  3906. floating point counterparts `ffontname', `ffontsize', and `ftextangle'.
  3907. Since these three operations may be invoked in any order, each of them
  3908. returns the size of the font that it selects, as a convenience to the
  3909. programmer.  This may differ slightly from the size specified in the
  3910. most recent call to `fontsize' or `ffontsize', since many Plotters have
  3911. only a limited repertory of fonts.  The above example plots each text
  3912. string in the "NewCenturySchlbk-Roman" font, which is available on
  3913. Postscript Plotters.  *Note Text Fonts::.
  3914.    If you replace "ps" by "X" in the call to `newpl', an X Plotter
  3915. rather than a Postscript Plotter will be used, and the spiral will be
  3916. drawn in a popped-up X window.  If your X display does not support the
  3917. "NewCenturySchlbk-Roman" font, you may substitute any other scalable
  3918. font, such as the widely available "utopia-medium-r-normal".  For the
  3919. format of font names, see *Note Text Fonts in X::.  If the X Plotter is
  3920. unable to retrieve the font you specify, it will first attempt to use a
  3921. default scalable font ("Helvetica"), and if that fails, use a default
  3922. Hershey vector font ("HersheySerif") instead.  Hershey fonts are
  3923. constructed from line segments, so each built-in Hershey font is
  3924. available on all types of Plotter.
  3925.    If you are using an older (pre-X11R6) X Window System display, you
  3926. will find that retrieving a scalable font is a time-consuming operation.
  3927. The above example may run slowly on some older X displays, since a new
  3928. font must be retrieved before each text string is drawn.  That is
  3929. because each text string has a different angle of inclination.  It is
  3930. possible to retrieve individual characters from an X11R6 display,
  3931. rather than retrieving an entire rasterized font.  If this feature is
  3932. available, the X Plotter will automatically take advantage of it to
  3933. save time.
  3934. File: plotutils.info,  Node: Sample C Animations,  Next: X Programming,  Prev: Sample C Drawings,  Up: C Programming
  3935. Sample animations in C
  3936. ----------------------
  3937.    You may use `libplot' to produce vector graphics animations on any
  3938. Plotter that does real-time plotting (i.e., an X, X Drawable,
  3939. Tektronix, or Metafile Plotter).  By definition, the `frames' in any
  3940. page of graphics are separated by invocations of `erase'.  So the
  3941. graphics display will be cleared after each frame.  If successive
  3942. frames differ only slightly, a smooth animation will result.
  3943.    The following is a sample application, written in C, that produces
  3944. an animation for the X Window System.  It displays a `drifting eye'.
  3945. As the eye drifts across a popped-up window from left to right, it
  3946. slowly rotates.  After the eye has drifted across twice, the window
  3947. will vanish.
  3948.      #include <stdio.h>
  3949.      #include <plot.h>
  3950.      
  3951.      int main ()
  3952.      {
  3953.        int handle, i = 0, j;
  3954.      
  3955.        /* set Plotter parameters */
  3956.        parampl ("BITMAPSIZE", "300x150");
  3957.        parampl ("VANISH_ON_DELETE", "yes");
  3958.        parampl ("USE_DOUBLE_BUFFERING", "yes");
  3959.      
  3960.        /* create an X Plotter with the specified parameters */
  3961.        if ((handle = newpl ("X", stdin, stdout, stderr)) < 0)
  3962.          {
  3963.            fprintf (stderr, "Couldn't create Plotter\n");
  3964.            return 1;
  3965.          }
  3966.        selectpl (handle);          /* select the Plotter for use */
  3967.      
  3968.        if (openpl () < 0)          /* open Plotter */
  3969.          {
  3970.            fprintf (stderr, "Couldn't open Plotter\n");
  3971.            return 1;
  3972.          }
  3973.        space (0, 0, 299, 149);     /* specify user coordinate system */
  3974.        linewidth (8);              /* width of lines in user coordinates */
  3975.        filltype (1);               /* objects will be filled */
  3976.        bgcolorname ("saddle brown");  /* background color for the window */
  3977.        for (j = 0; j < 300; j++)
  3978.          {
  3979.            erase ();               /* erase window */
  3980.            pencolorname ("red");   /* choose red pen, with cyan filling */
  3981.            fillcolorname ("cyan");
  3982.            ellipse (i, 75, 35, 50, i);  /* draw an ellipse */
  3983.            colorname ("black");    /* choose black pen, with black filling */
  3984.            circle (i, 75, 12);     /* draw a circle [the pupil] */
  3985.            i = (i + 2) % 300;      /* shift rightwards */
  3986.          }
  3987.        if (closepl () < 0)         /* close Plotter */
  3988.          {
  3989.            fprintf (stderr, "Couldn't close Plotter\n");
  3990.            return 1;
  3991.          }
  3992.      
  3993.        selectpl (0);               /* select default Plotter */
  3994.        if (deletepl (handle) < 0)  /* delete Plotter we used */
  3995.          {
  3996.            fprintf (stderr, "Couldn't delete Plotter\n");
  3997.            return 1;
  3998.          }
  3999.        return 0;
  4000.      }
  4001.    As you can see, this application begins by calling `parampl' several
  4002. times to set device driver parameters, and then calls `newpl' to create
  4003. an X Plotter.  The X Plotter window will have size 300x150 pixels.
  4004. This window will vanish when the Plotter is deleted.  If the
  4005. `VANISH_ON_DELETE' parameter were not set to "yes", the window would
  4006. remain on the screen until removed by the user (by typing `q' in it, or
  4007. by clicking with a mouse).
  4008.    Setting the parameter `USE_DOUBLE_BUFFERING' to "yes" is very
  4009. important if you wish to produce a smooth animation, with no jerkiness.
  4010. Normally, an X Plotter draws graphics into a window in real time, and
  4011. erases the window when `erase' is called.  But if double buffering is
  4012. used, each frame of graphics is written into an off-screen buffer, and
  4013. copied into the window, pixel by pixel, when `erase' is called or the
  4014. Plotter is closed.  This is a bit counterintuitive, but is exactly what
  4015. is needed for smooth animation.  On some high-end display devices you
  4016. may be able to do even better, by specifying "fast" rather than "yes".
  4017. This requests that the X Plotter take advantage of special hardware
  4018. support for double buffering.  If no such support is available, "fast"
  4019. means the same as "yes".
  4020.    After the Plotter is created, it is selected for use and opened.
  4021. When `openpl' is called, the window pops up, and the animation begins.
  4022. In the body of the for loop there is a call to `erase', and also a
  4023. sequence of `libplot' operations that draws the eye.  The pen color and
  4024. fill color are changed twice with each passage through the loop.  You
  4025. may wish to experiment with the animation parameters to produce the
  4026. best effects on your video hardware.
  4027.    The locations of the objects that are plotted in the animation are
  4028. expressed in terms of user coordinates, not pixel coordinates.  But the
  4029. call to `space' defines user and pixel coordinates to be effectively
  4030. the same.  User coordinates are chosen so that the lower left corner is
  4031. (0,0) and the upper right corner is (299,149).  Since this agrees with
  4032. the window size, individual pixels may be addressed in terms of integer
  4033. user coordinates.  For example, `point(299,149)' would set the pixel in
  4034. the upper right hand corner of the window to the current pen color.
  4035.    The following is another sample animation, this time of a rotating
  4036. letter `A'.
  4037.      #include <stdio.h>
  4038.      #include <plot.h>
  4039.      
  4040.      int main()
  4041.      {
  4042.        int handle, angle = 0;
  4043.      
  4044.        /* set Plotter parameters */
  4045.        parampl ("BITMAPSIZE", "300x300");
  4046.        parampl ("BG_COLOR", "blue"); /* background color for window */
  4047.        parampl ("USE_DOUBLE_BUFFERING", "yes");
  4048.      
  4049.        /* create an X Plotter with the specified parameters */
  4050.        handle = newpl ("X", stdin, stdout, stderr);
  4051.        selectpl (handle);
  4052.      
  4053.        /* open X Plotter, initialize coordinates, pen, and font */
  4054.        openpl ();
  4055.        fspace (0.0, 0.0, 1.0, 1.0);  /* use normalized coordinates */
  4056.        pencolorname ("white");
  4057.        ffontsize (1.0);
  4058.        fontname ("NewCenturySchlbk-Roman");
  4059.      
  4060.        fmove (.50,.50);              /* move to center */
  4061.        while (1)                     /* loop endlessly */
  4062.          {
  4063.            erase ();
  4064.            textangle (angle++);      /* set new rotation angle */
  4065.            alabel ('c', 'c', "A");   /* draw a centered `A' */
  4066.          }
  4067.        closepl();                    /* close Plotter */
  4068.      
  4069.        selectpl (0);                 /* select default Plotter */
  4070.        deletepl (handle);            /* delete Plotter we used */
  4071.        return 0;
  4072.      }
  4073.    This animation serves as a good test of the capabilities of an
  4074. X Window System display.  On a modern X11R6 display, animation will be
  4075. smooth and fast.  That is because X11R6 displays can rasterize
  4076. individual characters from a font without rasterizing the entire font.
  4077. If your X display does not support the "NewCenturySchlbk-Roman" font,
  4078. you may substitute any other scalable font, such as the widely
  4079. available "utopia-medium-r-normal".  For the format of font names, see
  4080. *Note Text Fonts in X::.  If the X Plotter is unable to retrieve the
  4081. font you specify, it will first attempt to use a default scalable font
  4082. ("Helvetica").  If that too fails, it will use a default Hershey vector
  4083. font ("HersheySerif") instead.
  4084.    Animations that use Hershey fonts are normally faster than ones that
  4085. use Postscript fonts or other X Window System fonts, since the Hershey
  4086. fonts are constructed from line segments.  Rasterizing line segments can
  4087. be done rapidly.  But if you use a scalable font such as
  4088. "NewCenturySchlbk-Roman" or "utopia-medium-r-normal", you will notice
  4089. that the rotation speeds up after the letter `A' has rotated through
  4090. 360 degrees.  That is because the `A' at angles past 360 degrees has
  4091. already been rasterized.
  4092. File: plotutils.info,  Node: X Programming,  Prev: Sample C Animations,  Up: C Programming
  4093. Advanced X Window System programming
  4094. ------------------------------------
  4095.    Applications that run under the X Window System are normally built
  4096. using Xt, the X Toolkit.  In Xt, an application is constructed from
  4097. `widgets' such as text entry fields, buttons, sliders, drawing areas,
  4098. etc.  When the application starts up, each widget is configured to
  4099. respond appropriately to `events', which include key presses and mouse
  4100. clicks.  After the widgets are configured, control is transferred to the
  4101. Xt event loop.
  4102.    GNU `libplot' can be used within the Xt event loop to draw vector
  4103. graphics.  For this, it would use one or more X Drawable Plotters.  An
  4104. X Drawable Plotter is a Plotter that can plot into an off-screen pixmap
  4105. or an on-screen window, such as a window associated with a widget.
  4106.    The following sample application shows how an X Drawable Plotter
  4107. would be used.  The application draws a `C' curve, as defined in a
  4108. previous section, in a popped-up window.  The usual Xt command-line
  4109. options may be used: the window background color is specified with the
  4110. "-bg" option, the window geometry with "-geometry", etc.  The curve is
  4111. initially drawn in red, but clicking once with the mouse will redraw it
  4112. in green.  A second mouse click will redraw it in red, and so forth.
  4113. The application will terminate when `q' is typed.
  4114.      #include <stdio.h>
  4115.      #include <plot.h>
  4116.      #include <X11/Xlib.h>
  4117.      #include <X11/Intrinsic.h>
  4118.      #include <X11/Shell.h>
  4119.      #include <X11/StringDefs.h>
  4120.      #include <X11/Core.h>
  4121.      
  4122.      int green = 0;                  /* draw in green, not red? */
  4123.      
  4124.      #define MAXORDER 12
  4125.      void draw_c_curve (double dx, double dy, int order)
  4126.      {
  4127.        if (order >= MAXORDER)
  4128.          fcontrel (dx, dy);          /* continue path along (dx, dy) */
  4129.        else
  4130.          {
  4131.            draw_c_curve (0.5 * (dx - dy), 0.5 * (dx + dy), order + 1);
  4132.            draw_c_curve (0.5 * (dx + dy), 0.5 * (dy - dx), order + 1);
  4133.          }
  4134.      }
  4135.      
  4136.      void Redraw (Widget w, XEvent *ev, String *params, Cardinal *n_params)
  4137.      {
  4138.        /* draw C curve */
  4139.        erase ();
  4140.        pencolorname (green ? "green" : "red");
  4141.        fmove (600.0, 300.0);
  4142.        draw_c_curve (0.0, 400.0, 0);
  4143.        endpath ();
  4144.      }
  4145.      
  4146.      void Toggle (Widget w, XEvent *ev, String *params, Cardinal *n_params)
  4147.      {
  4148.        green = (green ? 0 : 1);
  4149.        Redraw (w, ev, params, n_params);
  4150.      }
  4151.      
  4152.      void Quit (Widget w, XEvent *ev, String *params, Cardinal *n_params)
  4153.      {
  4154.        exit (0);
  4155.      }
  4156.      
  4157.      /* mapping of events to actions */
  4158.      static const String translations =
  4159.      "<Expose>:      redraw()\n\
  4160.      <Btn1Down>:     toggle()\n\
  4161.      <Key>q:         quit()";
  4162.      
  4163.      /* mapping of actions to subroutines */
  4164.      static XtActionsRec actions[] =
  4165.      {
  4166.        {"redraw",            Redraw},
  4167.        {"toggle",            Toggle},
  4168.        {"quit",              Quit},
  4169.      };
  4170.      
  4171.      /* default parameters for widgets */
  4172.      static String default_resources[] =
  4173.      {
  4174.        "Example*geometry:      250x250",
  4175.        (String)NULL
  4176.      };
  4177.      
  4178.      int main (int argc, char *argv[])
  4179.      {
  4180.        Arg wargs[10];                /* storage of widget args */
  4181.        Display *display;             /* X display */
  4182.        Widget shell, canvas;         /* toplevel widget; child */
  4183.        Window window;                /* child widget's window */
  4184.        XtAppContext app_con;         /* application context */
  4185.        int handle, i;
  4186.        char *bg_colorname = "white";
  4187.      
  4188.        /* take background color from command line */
  4189.        for (i = 0; i < argc - 1; i++)
  4190.          if (strcmp (argv[i], "-bg") == 0)
  4191.            bg_colorname = argv[i + 1];
  4192.      
  4193.        /* create toplevel shell widget */
  4194.        shell = XtAppInitialize (&app_con,
  4195.                                 (String)"Example", /* app class */
  4196.                                 NULL,              /* options */
  4197.                                 (Cardinal)0,       /* num of options */
  4198.                                 &argc,             /* command line */
  4199.                                 argv,              /* command line */
  4200.                                 default_resources,
  4201.                                 NULL,              /* ArgList */
  4202.                                 (Cardinal)0        /* num of Args */
  4203.                                 );
  4204.      
  4205.        /* set default widget parameters (including window size) */
  4206.        XtAppSetFallbackResources (app_con, default_resources);
  4207.      
  4208.        /* map actions to subroutines */
  4209.        XtAppAddActions (app_con, actions, XtNumber (actions));
  4210.      
  4211.        /* create canvas widget as child of shell widget; realize both */
  4212.        XtSetArg(wargs[0], XtNargc, argc);
  4213.        XtSetArg(wargs[1], XtNargv, argv);
  4214.        canvas = XtCreateManagedWidget ((String)"", coreWidgetClass,
  4215.                                        shell, wargs, (Cardinal)2);
  4216.        XtRealizeWidget (shell);
  4217.      
  4218.        /* for the canvas widget, map events to actions */
  4219.        XtSetArg (wargs[0], XtNtranslations,
  4220.                  XtParseTranslationTable (translations));
  4221.        XtSetValues (canvas, wargs, (Cardinal)1);
  4222.      
  4223.        /* initialize GNU libplot */
  4224.        display = XtDisplay (canvas);
  4225.        parampl ("XDRAWABLE_DISPLAY", display);
  4226.        window = XtWindow (canvas);
  4227.        parampl ("XDRAWABLE_DRAWABLE1", &window);
  4228.        parampl ("BG_COLOR", bg_colorname);
  4229.        handle = newpl ("Xdrawable", NULL, NULL, stderr);
  4230.        selectpl (handle);
  4231.        openpl ();
  4232.        fspace (0.0, 0.0, 1000.0, 1000.0);
  4233.        flinewidth (0.25);
  4234.      
  4235.        /* transfer control to X Toolkit event loop (doesn't return) */
  4236.        XtAppMainLoop (app_con);
  4237.      
  4238.        return 1;
  4239.      }
  4240.    Even if you are not familiar with X Window System programming, the
  4241. structure of this application should be clear.  It defines three
  4242. callbacks: `Redraw', `Toggle', and `Quit'.  They are invoked
  4243. respectively in response to (1) a window expose event or mouse click,
  4244. (2) a mouse click, and (3) a typed `q'.  The first drawing of the
  4245. `C' curve (in red) takes place because the window receives an initial
  4246. expose event.
  4247.    This example could be extended to take window resizing into account.
  4248. Actually, X Drawable Plotters are usually used to draw vector graphics
  4249. in off-screen pixmaps rather than on-screen windows.  Pixmaps, unlike
  4250. windows, are never resized.
  4251. File: plotutils.info,  Node: Functions,  Next: Driver Parameters,  Prev: C Programming,  Up: libplot
  4252. The functions in `libplot': A detailed listing
  4253. ==============================================
  4254.    In the current release of GNU `libplot', any Plotter supports 81
  4255. distinct operations.  A language binding for `libplot' necessarily
  4256. includes 81 functions that correspond to these operations.  A language
  4257. binding may also include functions for creating, selecting, and
  4258. deleting Plotters.  For example, the C binding includes the four
  4259. additional functions `newpl', `selectpl', `deletepl', and `parampl'.
  4260. *Note The C API::.
  4261.    The 81 functions that operate on a specified Plotter are divided into
  4262. the four sets tabulated below.
  4263.    Many functions come in two versions: integer and double precision
  4264. floating point.  Internally, `libplot' uses double precision floating
  4265. point.  The integer versions are provided for backward compatibility.
  4266. If there are two versions of a function, the name of the floating point
  4267. version begins with the letter `f'.
  4268.    Many functions come in both absolute and relative versions, also.
  4269. The latter use relative coordinates (i.e., coordinates relative to the
  4270. current position of the graphics cursor), and in the C binding their
  4271. names end in `rel'.
  4272.    Currently, only a few of the 81 functions have meaningful return
  4273. values.
  4274. * Menu:
  4275. * Setup Functions::     Functions that open, initialize or close a Plotter
  4276. * Drawing Functions::   Functions that draw objects
  4277. * Attribute Functions:: Functions that affect drawing attributes
  4278. * Mapping Functions::   Functions affecting the user -> device coordinate map
  4279. File: plotutils.info,  Node: Setup Functions,  Next: Drawing Functions,  Prev: Functions,  Up: Functions
  4280. Setup functions
  4281. ---------------
  4282.    The following are the "setup functions" in the C binding for
  4283. `libplot'.  They are the basic functions that open, initialize, or
  4284. close an already-created Plotter.  They are listed in the approximate
  4285. order in which they would be called.
  4286. int openpl ();
  4287.      openpl opens a Plotter, i.e., begins a page of graphics.  This
  4288.      resets the Plotter's drawing attributes to their default values.
  4289.      A negative return value indicates the Plotter could not be opened.
  4290.      Currently, an X Plotter pops up a new window on an X Window System
  4291.      display for each page of graphics, i.e., with each invocation of
  4292.      `openpl'.  Future releases may support window re-use.
  4293. int bgcolor (int RED, int GREEN, int BLUE);
  4294.      bgcolor sets the background color for the Plotter's graphics
  4295.      display, using a 48-bit RGB color model.  The arguments RED, GREEN
  4296.      and BLUE specify the red, green and blue intensities of the
  4297.      background color.  Each is an integer in the range
  4298.      0x0000...0xffff, i.e., 0...65535.  The choice (0, 0, 0) signifies
  4299.      black, and the choice (65535, 65535, 65535) signifies white.
  4300.      bgcolor has an effect only on X Plotters and X Drawable Plotters.
  4301.      Its effect is simple: the next time the erase operation is invoked
  4302.      on such a Plotter, its display will be filled with the specified
  4303.      color.
  4304. int bgcolorname (const char *NAME);
  4305.      bgcolorname sets the background color for the the graphics display
  4306.      to be NAME.  For information on what color names are recognized,
  4307.      see *Note Color Names::.  Unrecognized colors are interpreted as
  4308.      "white".
  4309.      bgcolorname has an effect only on X Plotters and X Drawable
  4310.      Plotters.  Its effect is simple: the next time the erase operation
  4311.      is invoked on such a Plotter, its display will be filled with the
  4312.      specified color.
  4313. int erase ();
  4314.      erase begins the next frame of a multiframe page, by clearing all
  4315.      previously plotted objects from the graphics display, and filling
  4316.      it with the background color (if any).
  4317.      It is frequently useful to invoke erase at the beginning of each
  4318.      page, i.e., immediately after invoking openpl.  That is because
  4319.      some Plotters are persistent, in the sense that objects drawn
  4320.      within an `openpl'...`closepl' pair remain on the graphics display
  4321.      even after a new page is begun by a subsequent invocation of
  4322.      `openpl'.  Currently, only X Drawable Plotters and Tektronix
  4323.      Plotters are persistent.  Future releases may support optional
  4324.      persistence for X Plotters also.
  4325.      On X Plotters and X Drawable Plotters the effects of invoking erase
  4326.      will be altogether different if the device driver parameter
  4327.      `USE_DOUBLE_BUFFERING' is set to "yes".  In this case, objects
  4328.      will be written to an off-screen buffer rather than to the graphics
  4329.      display, and invoking erase will (1) copy the contents of this
  4330.      buffer to the display, and (2) erase the buffer by filling it with
  4331.      the background color.  This feature facilitates smooth animation.
  4332.      *Note Driver Parameters::.
  4333. int space (int X0, int Y0, int X1, int Y1);
  4334. int fspace (double X0, double Y0, double X1, double Y1);
  4335.      space and fspace take two pairs of arguments, specifying the
  4336.      positions of the lower left corner and upper right corner of the
  4337.      graphics display, in user coordinates.  In other words, calling
  4338.      space or fspace sets the affine transformation from user
  4339.      coordinates to device coordinates.  One of these operations must be
  4340.      performed at the beginning of each page of graphics, i.e.,
  4341.      immediately after openpl is invoked.
  4342. int space2 (int X0, int Y0, int X1, int Y1, int X2, int Y2);
  4343. int fspace2 (double X0, double Y0, double X1, double Y1, double X2, double Y2);
  4344.      space2 and fspace2 are extended versions of space and fspace, and
  4345.      may be used instead.  Their arguments are the three defining
  4346.      vertices of an `affine window' (a drawing parallelogram), in user
  4347.      coordinates.  The specified vertices are the lower left, the lower
  4348.      right, and the upper left.  This window will be mapped affinely
  4349.      onto the graphics display.
  4350. int havecap (const char *S);
  4351.      havecap tests whether or not a Plotter, which need not be open, has
  4352.      a specified capability.  The return value is 0, 1, or 2,
  4353.      signifying no/yes/maybe.  For unrecognized capabilities the return
  4354.      value is zero.  Recognized capabilities include "SOLID_FILL",
  4355.      "WIDE_LINES" (i.e., the ability to draw lines with a non-default
  4356.      width), and "SETTABLE_BACKGROUND" (the ability to set the color of
  4357.      the background).  They also include "HERSHEY_FONTS", "PS_FONTS",
  4358.      and "PCL_FONTS", which indicate whether or not fonts of a
  4359.      particular class are supported.  *Note Text Fonts::.
  4360.      The `maybe' value is returned for most capabilities by Metafile
  4361.      Plotters, since they do no drawing themselves.  The output of a
  4362.      Metafile Plotter must be translated to another format, or
  4363.      displayed, by invoking `plot'.
  4364. int flushpl ();
  4365.      flushpl flushes (i.e., pushes onward) all plotting commands to the
  4366.      display device.  This is useful only if the currently selected
  4367.      Plotter does real-time plotting, since it may be used to ensure
  4368.      that all previously plotted objects have been sent to the display
  4369.      and are visible to the user.  It has no effect on Plotters that do
  4370.      not do real-time plotting.
  4371. int closepl ();
  4372.      closepl closes a Plotter, i.e., ends a page of graphics.
  4373.      A negative return value indicates the Plotter could not be closed.
  4374.      In general, Plotters that do not do real-time plotting (i.e.,
  4375.      Postscript, Fig, and HP-GL Plotters) wait until they are deleted
  4376.      before outputing their page(s) of graphics.  However, HP-GL
  4377.      Plotters in the present release of `libplot' output pages of
  4378.      graphics individually.
  4379. FILE *outfile (FILE *FP);
  4380.      outfile, which must be called outside a openpl...closepl pair,
  4381.      redirects all graphics output from a Plotter to the stream FP.
  4382.      The previous output stream is returned.
  4383.      This operation is useful on Plotters that are designed to be
  4384.      opened only once; in particular, on Fig Plotters.  On other
  4385.      Plotters its use is strongly deprecated.  On Plotters that do not
  4386.      have an output stream in the conventional sense, i.e., on
  4387.      X Plotters and X Drawable Plotters, it has no effect.
  4388. File: plotutils.info,  Node: Drawing Functions,  Next: Attribute Functions,  Prev: Setup Functions,  Up: Functions
  4389. Object-drawing functions
  4390. ------------------------
  4391.    The following are the "drawing functions" in the C binding for
  4392. `libplot'.  When invoked on a Plotter, these functions cause it to draw
  4393. objects (paths, circles, ellipses, points, markers, and text strings)
  4394. on the associated graphics display.  A *path* is a sequence of line
  4395. segments and arcs (either circular or elliptic).  Paths may be drawn
  4396. incrementally, one line segment or arc at a time.
  4397. int alabel (int HORIZ_JUSTIFY, int VERT_JUSTIFY, const char *S);
  4398.      alabel takes three arguments HORIZ_JUSTIFY, VERT_JUSTIFY, and S,
  4399.      which specify an `adjusted label,' i.e., a justified text string.
  4400.      The path under construction (if any) is ended, and the string S is
  4401.      drawn according to the specified justifications.  If HORIZ_JUSTIFY
  4402.      is equal to `l', `c', or `r', then the string will be drawn with
  4403.      left, center or right justification, relative to the current
  4404.      graphics cursor position.  If VERT_JUSTIFY is equal to `b', `x',
  4405.      `c', or `t', then the bottom, baseline, center or top of the
  4406.      string will be placed even with the current graphics cursor
  4407.      position.  The graphics cursor is moved to the right end of the
  4408.      string if left justification is specified, and to the left end if
  4409.      right justification is specified.
  4410.      The string may contain escape sequences of various sorts (see
  4411.      *Note Text String Format::), though it should not contain line
  4412.      feeds or carriage returns.  In fact it should include only
  4413.      printable characters, from the byte ranges 0x20...0x7e and
  4414.      0xa0...0xff.  The string may be plotted at a nonzero angle, if
  4415.      `textangle' has been called.
  4416. int arc (int XC, int YC, int X0, int Y0, int X1, int Y1);
  4417. int farc (double XC, double YC, double X0, double Y0, double X1, double Y1);
  4418. int arcrel (int XC, int YC, int X0, int Y0, int X1, int Y1);
  4419. int farcrel (double XC, double YC, double X0, double Y0, double X1, double Y1);
  4420.      arc and farc take six arguments specifying the beginning (X0, Y0),
  4421.      end (X1, Y1), and center (XC, YC) of a circular arc.  If the
  4422.      graphics cursor is at (X0, Y0) and a path is under construction,
  4423.      then the arc is added to the path.  Otherwise the current path
  4424.      (if any) is ended, and the arc begins a new path.  In all cases
  4425.      the graphics cursor is moved to (X1, Y1).
  4426.      The direction of the arc (clockwise or counterclockwise) is
  4427.      determined by the convention that the arc, centered at (XC, YC),
  4428.      sweep through an angle of at most 180 degrees.  If the three
  4429.      points appear to be collinear, the direction is taken to be
  4430.      counterclockwise.  If (XC, YC) is not equidistant from (X0, Y0) and
  4431.      (X1, Y1) as it should be, it is corrected by being moved to the
  4432.      closest point on the perpendicular bisector of the line segment
  4433.      joining (X0, Y0) and (X1, Y1).  arcrel and farcrel are similar to
  4434.      `arc' and `farc', but use cursor-relative coordinates.
  4435. int box (int X1, int y1, int X2, int Y2);
  4436. int fbox (double X1, double Y1, double X2, double Y2);
  4437. int boxrel (int X1, int y1, int X2, int Y2);
  4438. int fboxrel (double X1, double y1, double X2, double Y2);
  4439.      box and fbox take four arguments specifying the lower left corner
  4440.      (X1, Y1) and upper right corner (X2, Y2) of a `box', or rectangle.
  4441.      The path under construction (if any) is ended, and the box is
  4442.      drawn as a new path.  This path is also ended, and the graphics
  4443.      cursor is moved to the midpoint of the box.  boxrel and fboxrel
  4444.      are similar to box and fbox, but use cursor-relative coordinates.
  4445. int circle (int XC, int YC, int R);
  4446. int fcircle (double XC, double YC, double R);
  4447. int circlerel (int XC, int YC, int R);
  4448. int fcirclerel (double XC, double YC, double R);
  4449.      circle and fcircle take three arguments specifying the center (XC,
  4450.      YC) and radius (R) of a circle.  The path under construction
  4451.      (if any) is ended, and the circle is drawn.  The graphics cursor
  4452.      is moved to (XC, YC).  circlerel and fcirclerel are similar to
  4453.      circle and fcircle, but use cursor-relative coordinates for XC and
  4454.      YC.
  4455. int cont (int X, int Y);
  4456. int fcont (double X, double Y);
  4457. int contrel (int X, int Y);
  4458. int fcontrel (double X, double Y);
  4459.      cont and fcont take two arguments specifying the coordinates (X,
  4460.      Y) of a point.  If a path is under construction, the line segment
  4461.      from the current graphics cursor position to the point (X, Y) is
  4462.      added to it.  Otherwise the line segment begins a new path.  In
  4463.      all cases the graphics cursor is moved to (X, Y).  contrel and
  4464.      fcontrel are similar to cont and fcont, but use cursor-relative
  4465.      coordinates.
  4466. int ellarc (int XC, int YC, int X0, int Y0, int X1, int Y1);
  4467. int fellarc (double XC, double YC, double X0, double Y0, double X1, double Y1);
  4468. int ellarcrel (int XC, int YC, int X0, int Y0, int X1, int Y1);
  4469. int fellarcrel (double XC, double YC, double X0, double Y0, double X1, double Y1);
  4470.      ellarc and fellarc take six arguments specifying the three points
  4471.      `pc'=(XC,YC), `p0'=(X0,Y0), and `p1'=(X1,Y1) that define a
  4472.      so-called quarter ellipse.  This is an elliptic arc from `p0' to
  4473.      `p1' with center `pc'.  If the graphics cursor is at point `p0'
  4474.      and a path is under construction, the quarter-ellipse is added to
  4475.      it.  Otherwise the path under construction (if any) is ended, and
  4476.      the quarter-ellipse begins a new path.  In all cases the graphics
  4477.      cursor is moved to `p1'.
  4478.      The quarter-ellipse is an affinely transformed version of a quarter
  4479.      circle.  It is drawn so as to have control points `p0', `p1', and
  4480.      `p0'+`p1'-`pc'.  This means that it is tangent at `p0' to the line
  4481.      segment joining `p0' to `p0'+`p1'-`pc', and is tangent at `p1' to
  4482.      the line segment joining `p1' to `p0'+`p1'-`pc'.  So it fits
  4483.      snugly into a triangle with these three control points as
  4484.      vertices.  Notice that the third control point is the reflection of
  4485.      `pc 'through the line joining `p0' and `p1'.  ellarcrel and
  4486.      fellarcrel are similar to ellarc and fellarc, but use
  4487.      cursor-relative coordinates.
  4488. int ellipse (int XC, int YC, int RX, int RY, int ANGLE);
  4489. int fellipse (double XC, double YC, double RX, double RY, double ANGLE);
  4490. int ellipserel (int XC, int YC, int RX, int RY, int ANGLE);
  4491. int fellipserel (double XC, double YC, double RX, double RY, double ANGLE);
  4492.      ellipse and fellipse take five arguments specifying the center
  4493.      (XC, YC) of an ellipse, the lengths of its semiaxes (RX and RY),
  4494.      and the inclination of the first semiaxis in the counterclockwise
  4495.      direction from the x axis in the user coordinate system.  The path
  4496.      under construction (if any) is ended, and the ellipse is drawn.
  4497.      The graphics cursor is moved to (XC, YC).  ellipserel and
  4498.      fellipserel are similar to ellipse and fellipse, but use
  4499.      cursor-relative coordinates.
  4500. int endpath ();
  4501.      endpath terminates the path under construction, if any.  Paths,
  4502.      which are formed by repeated calls to cont or fcont, arc or farc,
  4503.      ellarc or fellarc, and line or fline, are also terminated if any
  4504.      other object is drawn or any path-related drawing attribute is
  4505.      set.  So endpath is almost redundant.  However, if a Plotter plots
  4506.      objects in real time, calling endpath will ensure that a
  4507.      constructed path is drawn on the graphics display without delay.
  4508. int label (const char *S);
  4509.      label takes a single string argument S and draws the text
  4510.      contained in S at the current graphics cursor position.  The text
  4511.      is left justified, and the graphics cursor is moved to the right
  4512.      end of the string.  This function is provided for backward
  4513.      compatibility; the function call label(S) is equivalent to
  4514.      alabel(`l',`x',S).
  4515. int labelwidth (const char *S);
  4516. double flabelwidth (const char *S);
  4517.      labelwidth and flabelwidth compute and return the width of a
  4518.      string in the current font, in the user coordinate system.  The
  4519.      string is not plotted.
  4520. int line (int X1, int Y1, int X2, int Y2);
  4521. int fline (double X1, double y1, double X2, double Y2);
  4522. int linerel (int X1, int y1, int X2, int Y2);
  4523. int flinerel (double X1, double y1, double X2, double Y2);
  4524.      line and fline take four arguments specifying the start point (X1,
  4525.      Y1) and end point (X2, Y2) of a line segment.  If the graphics
  4526.      cursor is at (X1, Y1) and a path is under construction, the line
  4527.      segment is added to it.  Otherwise the path under construction
  4528.      (if any) is ended, and the line segment begins a new path.  In all
  4529.      cases the graphics cursor is moved to (X2, Y2).  linerel and
  4530.      flinerel are similar to line and fline, but use cursor-relative
  4531.      coordinates.
  4532. int marker (int X, int Y, int TYPE, int SIZE);
  4533. int fmarker (double X, double Y, int TYPE, double SIZE);
  4534. int markerrel (int X, int Y, int TYPE, int SIZE);
  4535. int fmarkerrel (double X, double Y, int TYPE, double SIZE);
  4536.      marker and fmarker take four arguments specifying the location
  4537.      (X,Y) of a marker symbol, its type, and its size in user
  4538.      coordinates.  The path under construction (if any) is ended, and
  4539.      the marker symbol is plotted.  The graphics cursor is moved to
  4540.      (X,Y).  markerrel and fmarkerrel are similar to marker and
  4541.      fmarker, but use cursor-relative coordinates for the position
  4542.      (X,Y).
  4543.      Marker symbol types 0 through 31 are taken from a standard set, and
  4544.      marker symbol types 32 and above are interpreted as the index of a
  4545.      character in the current text font.  *Note Marker Symbols::.
  4546. int move (int X, int Y);
  4547. int fmove (double X, double Y);
  4548. int moverel (int X, int Y);
  4549. int fmoverel (double X, double Y);
  4550.      move and fmove take two arguments specifying the coordinates (X,
  4551.      Y) of a point to which the graphics cursor should be moved.  The
  4552.      path under construction (if any) is ended, and the graphics cursor
  4553.      is moved to (X, Y).  This is equivalent to lifting the pen on a
  4554.      plotter and moving it to a new position, without drawing any line.
  4555.      moverel and fmoverel are similar to move and fmove, but use
  4556.      cursor-relative coordinates.
  4557. int point (int X, int Y);
  4558. int fpoint (double X, double Y);
  4559. int pointrel (int X, int Y);
  4560. int fpointrel (double X, double Y);
  4561.      point and fpoint take two arguments specifying the coordinates (X,
  4562.      Y) of a point.  The path under construction (if any) is ended, and
  4563.      the point is plotted.  (A `point' is usually a small solid circle,
  4564.      perhaps the smallest that can be plotted.)  The graphics cursor is
  4565.      moved to (X, Y).  pointrel and fpointrel are similar to point and
  4566.      fpoint, but use cursor-relative coordinates.
  4567. File: plotutils.info,  Node: Attribute Functions,  Next: Mapping Functions,  Prev: Drawing Functions,  Up: Functions
  4568. Attribute-setting functions
  4569. ---------------------------
  4570.    The following are the "attribute functions" in the C binding for
  4571. `libplot'.  When invoked on a Plotter, these functions set its drawing
  4572. attributes, or save them or restore them.  Path-related attributes
  4573. include pen color, fill color, line width, line style, cap style, and
  4574. join style.  Text-related attributes include pen color, font name, font
  4575. size, and text angle.
  4576.    Setting any path-related drawing attribute automatically terminates
  4577. the path under construction (if any), as if the `endpath' operation had
  4578. been invoked.
  4579. int capmod (const char *S);
  4580.      capmod sets the cap mode (i.e., cap style) for all paths
  4581.      subsequently drawn on the graphics display.  Recognized styles are
  4582.      "butt" (the default), "round", and "projecting".  This function
  4583.      has no effect on Tektronix Plotters.  Also, it has no effect on
  4584.      HP-GL Plotters if the parameter `HPGL_VERSION' is set to a value
  4585.      less than "2" (the default).  *Note Driver Parameters::.
  4586. int color (int RED, int GREEN, int BLUE);
  4587.      color is a convenience function.  Calling color is equivalent to
  4588.      calling both pencolor and fillcolor, to set both the the pen color
  4589.      and fill color of all objects subsequently drawn on the graphics
  4590.      display.  Note that the physical fill color depends also on the
  4591.      fill fraction, which is specified by calling filltype.
  4592. int colorname (const char *NAME);
  4593.      colorname is a convenience function.  Calling colorname is
  4594.      equivalent to calling both pencolorname and fillcolorname, to set
  4595.      both the the pen color and fill color of all objects subsequently
  4596.      drawn on the graphics display.  Note that the physical fill color
  4597.      depends also on the fill fraction, which is specified by calling
  4598.      filltype.
  4599. int filltype (int LEVEL);
  4600.      filltype sets the fill fraction for all subsequently drawn objects.
  4601.      A value of 0 for LEVEL indicates that objects should be unfilled,
  4602.      or transparent.  This is the default.  A value in the range
  4603.      0x0001...0xffff, i.e., 1...65535, indicates that objects should be
  4604.      filled.  A value of 1 signifies 100% filling (the fill color will
  4605.      simply be the color specified by calling fillcolor or
  4606.      fillcolorname).  If LEVEL=0xffff, the fill color will be white.
  4607.      Values between 0x0001 and 0xffff are interpreted as specifying a
  4608.      desaturation, or gray level.  For example, 0x8000 specifies 50%
  4609.      filling (the fill color will be intermediate between the color
  4610.      specified by calling fillcolor or fillcolorname, and white).
  4611.      If the object to be filled is a self-intersecting path, the
  4612.      `even-odd rule' will be applied to determine which points are
  4613.      inside, i.e., which of the regions bounded by the path should be
  4614.      filled.  The even-odd rule is explained in the `Postscript
  4615.      Language Reference Manual'.
  4616.      Tektronix Plotters do not support filling, and HP-GL Plotters
  4617.      support filling of arbitrary paths only if the parameter
  4618.      `HPGL_VERSION' is equal to "1.5" or "2" (the default).  (If the
  4619.      version is "1" then only circles and rectangles aligned with the
  4620.      coordinate axes may be filled.)  *Opaque* filling, including white
  4621.      filling, is supported only if the parameter `HPGL_VERSION' is "2"
  4622.      and the parameter `HPGL_OPAQUE_MODE' is "yes" (the default).
  4623.      *Note Driver Parameters::.
  4624. int fillcolor (int RED, int GREEN, int BLUE);
  4625.      fillcolor sets the fill color of all objects subsequently drawn on
  4626.      the graphics display, using a 48-bit RGB color model.  The
  4627.      arguments RED, GREEN and BLUE specify the red, green and blue
  4628.      intensities of the fill color.  Each is an integer in the range
  4629.      0x0000...0xffff, i.e., 0...65535.  The choice (0, 0, 0) signifies
  4630.      black, and the choice (65535, 65535, 65535) signifies white.  Note
  4631.      that the physical fill color depends also on the fill fraction,
  4632.      which is specified by calling filltype.
  4633. int fillcolorname (const char *NAME);
  4634.      fillcolorname sets the fill color of all objects subsequently drawn
  4635.      on the graphics display to be NAME.  For information on what color
  4636.      names are recognized, see *Note Color Names::.  Unrecognized
  4637.      colors are interpreted as "black".  Note that the physical fill
  4638.      color depends also on the fill fraction, which is specified by
  4639.      calling filltype.
  4640. int fontname (const char *FONT_NAME);
  4641. double ffontname (const char *FONT_NAME);
  4642.      fontname and ffontname take a single case-insensitive string
  4643.      argument, FONT_NAME, specifying the name of the font to be used
  4644.      for all text strings subsequently drawn on the graphics display.
  4645.      (The font for plotting strings is fully specified by calling
  4646.      fontname, fontsize, and textangle.)  The default font name depends
  4647.      on the type of Plotter.  It is "Helvetica" for all Plotters except
  4648.      Tektronix and HP-GL Plotters, for which it is "HersheySerif".  If
  4649.      the argument FONT_NAME is NULL or the empty string, or the font is
  4650.      not available, the default font name will be used.  Which fonts are
  4651.      available also depends on the type of Plotter; for a list of all
  4652.      available fonts, see *Note Text Fonts::.  The size of the font in
  4653.      user coordinates is returned.
  4654. int fontsize (int SIZE);
  4655. double ffontsize (double SIZE);
  4656.      fontsize and ffontsize take a single argument, interpreted as the
  4657.      size, in the user coordinate system, of the font to be used for all
  4658.      text strings subsequently drawn on the graphics display.  (The
  4659.      font for plotting strings is fully specified by calling fontname,
  4660.      fontsize, and textangle.)  The size of the font in user
  4661.      coordinates is returned.  A negative value for SIZE sets the size
  4662.      to a default value, which depends on the type of Plotter.
  4663. int joinmod (const char *S);
  4664.      joinmod sets the join mode (i.e., join style) for all paths
  4665.      subsequently drawn on the graphics display.  Recognized styles are
  4666.      "miter" (the default), "round", and "bevel".  This function has no
  4667.      effect on Tektronix Plotters.  Also, it has no effect on HP-GL
  4668.      Plotters if the parameter `HPGL_VERSION' is set to a value less
  4669.      than "2" (the default). *Note Driver Parameters::.
  4670. int linemod (const char *S);
  4671.      linemod sets the linemode (i.e., line style) for all paths,
  4672.      circles, and ellipses subsequently drawn on the graphics display.
  4673.      The supported linemodes are "disconnected", "solid", "dotted",
  4674.      "dotdashed", "shortdashed", and "longdashed".  The final five
  4675.      correspond more or less to the following bit patterns:
  4676.           "solid"             --------------------------------
  4677.           "dotted"            - - - - - - - - - - - - - - - -
  4678.           "dotdashed"         -----------  -  -----------  -
  4679.           "shortdashed"       --------        --------
  4680.           "longdashed"        ------------    ------------
  4681.      For sufficiently wide lines, the distance over which a pattern
  4682.      repeats is scaled proportionately to the line width.
  4683.      A path that is drawn when the linemode is "disconnected" will be
  4684.      rendered as a set of filled circles, each of which has diameter
  4685.      equal to the nominal line width.  One of these circles will be
  4686.      centered on each of the juncture points of the path (i.e., the
  4687.      endpoints of the line segments or arcs from which it is
  4688.      constructed).  Circles and ellipses that are drawn when the
  4689.      linemode is "disconnected" will be invisible.  Disconnected paths,
  4690.      circles, and ellipses are not filled.
  4691. int linewidth (int SIZE);
  4692. int flinewidth (double SIZE);
  4693.      linewidth and flinewidth set the width, in the user coordinate
  4694.      system, of all paths, circles, and ellipses subsequently drawn on
  4695.      the graphics display.  A negative value means that a default width
  4696.      should be used.  This default width depends on the type of
  4697.      Plotter.  The interpretation of zero line width does also (for
  4698.      some types of Plotter, a zero-width line is the thinnest line that
  4699.      can be drawn; for others, a zero-width line is invisible).
  4700.      Tektronix Plotters do not support drawing with other than a default
  4701.      width, and HP-GL Plotters do not support doing so if the parameter
  4702.      `HPGL_VERSION' is set to a value less than "2" (the default; see
  4703.      *Note Driver Parameters::).
  4704. int pencolor (int RED, int GREEN, int BLUE);
  4705.      pencolor sets the pen color of all objects subsequently drawn on
  4706.      the graphics display, using a 48-bit RGB color model.  The
  4707.      arguments RED, GREEN and BLUE specify the red, green and blue
  4708.      intensities of the pen color.  Each is an integer in the range
  4709.      0x0000...0xffff, i.e., 0...65535.  The choice (0, 0, 0) signifies
  4710.      black, and the choice (65535, 65535, 65535) signifies white.
  4711.      HP-GL Plotters support drawing with a white pen only if the value
  4712.      of the parameter `HPGL_VERSION' is "2" (the default), and the
  4713.      value of the parameter `HPGL_OPAQUE_MODE' is "yes" (the default).
  4714.      *Note Driver Parameters::.
  4715. int pencolorname (const char *NAME);
  4716.      pencolorname sets the pen color of all objects subsequently drawn
  4717.      on the graphics display to be NAME.  For information on what color
  4718.      names are recognized, see *Note Color Names::.  Unrecognized
  4719.      colors are interpreted as "black".
  4720.      HP-GL Plotters support drawing with a white pen only if the value
  4721.      of the parameter `HPGL_VERSION' is "2" (the default) and the value
  4722.      of the parameter `HPGL_OPAQUE_MODE' is "yes" (the default).  *Note
  4723.      Driver Parameters::.
  4724. int restorestate ();
  4725.      restorestate pops the current graphics context off the stack of
  4726.      drawing states.  The graphics context consists largely of
  4727.      `libplot''s drawing attributes, which are set by the attribute
  4728.      functions documented in this section.  So popping off the graphics
  4729.      context restores the drawing attributes to values they previously
  4730.      had.  A path under construction is regarded as part of the graphics
  4731.      context.  For this reason, calling restorestate automatically calls
  4732.      endpath to terminate the path under construction, if any.  All
  4733.      graphics contexts on the stack are popped off when `closepl' is
  4734.      called, as if `restorestate' had been called repeatedly.
  4735. int savestate ();
  4736.      savestate pushes the current graphics context onto the stack of
  4737.      drawing states.  The graphics context consists largely of
  4738.      `libplot''s drawing attributes, which are set by the attribute
  4739.      functions documented in this section.  A path under construction,
  4740.      if any, is regarded as part of the graphics context.  That is
  4741.      because paths may be drawn incrementally, one line segment or arc
  4742.      at a time.  When a graphics context is returned to, the path under
  4743.      construction may be continued.
  4744. int textangle (int ANGLE);
  4745. double ftextangle (double ANGLE);
  4746.      textangle and ftextangle take one argument, which specifies the
  4747.      angle in degrees counterclockwise from the x (horizontal) axis in
  4748.      the user coordinate system, for text strings subsequently drawn on
  4749.      the graphics display.  The default angle is zero.  (The font for
  4750.      plotting strings is fully specified by calling fontname, fontsize,
  4751.      and textangle.)  The size of the font for plotting strings, in user
  4752.      coordinates, is returned.
  4753. File: plotutils.info,  Node: Mapping Functions,  Prev: Attribute Functions,  Up: Functions
  4754. Mapping functions
  4755. -----------------
  4756.    The following are the "mapping functions" in the C binding for
  4757. `libplot'.  When invoked on a Plotter, these functions affect the
  4758. affine transformation it employs for mapping from the user coordinate
  4759. system to the device coordinate system.  They may be viewed as
  4760. performing transformations of the user coordinate system.  Their names
  4761. resemble those of the corresponding functions in the Postscript
  4762. language.  For information on how to use them to draw graphics
  4763. efficiently, consult any good book on Postscript programming, or the
  4764. `Postscript Language Reference Manual'.
  4765. int fconcat (double M0, double M1, double M2, double M3, double TX, double TY);
  4766.      Apply a Postscript-style transformation matrix, i.e., affine map,
  4767.      to the user coordinate system.  That is, apply the linear
  4768.      transformation defined by the two-by-two matrix [M0 M1 M2 M3] to
  4769.      the user coordinate system, and also translate by TX units in the
  4770.      x direction and TY units in the y direction, relative to the
  4771.      former user coordinate system.  The following three functions
  4772.      (frotate, fscale, ftranslate) are convenience functions that are
  4773.      special cases of fconcat.
  4774. int frotate (double THETA);
  4775.      Rotate the user coordinate system axes about their origin by THETA
  4776.      degrees, with respect to their former orientation.  The position
  4777.      of the user coordinate origin and the size of the x and y units
  4778.      remain unchanged.
  4779. int fscale (double SX, double SY);
  4780.      Make the x and y units in the user coordinate system be the size
  4781.      of SX and SY units in the former user coordinate system.  The
  4782.      position of the user coordinate origin and the orientation of the
  4783.      coordinate axes are unchanged.
  4784. int ftranslate (double TX, double TY);
  4785.      Move the origin of the user coordinate system by TX units in the
  4786.      x direction and TY units in the y direction, relative to the
  4787.      former user coordinate system.  The size of the x and y units and
  4788.      the orientation of the coordinate axes are unchanged.
  4789. File: plotutils.info,  Node: Driver Parameters,  Prev: Functions,  Up: libplot
  4790. Device driver parameters
  4791. ========================
  4792.    In designing the `libplot' library, every effort was made to make
  4793. the Plotter interface independent of the type of Plotter.  To the
  4794. extent that device dependence exists, it is captured by a manageable
  4795. number of *device driver parameters*.
  4796.    In the C binding, a value for any parameter may be specified by
  4797. calling the `parampl' function.  The `parampl' function does not
  4798. operate on any particular Plotter: it belongs to the C binding as a
  4799. whole.  The parameter values used by any Plotter are constant over the
  4800. lifetime of the Plotter, and are those that were in effect when the
  4801. Plotter was created.  Each driver parameter has a value that is allowed
  4802. to be a generic pointer (a `void *').  For most parameters, this value
  4803. should be a string (a `char *').  `parampl' may be called any number of
  4804. times.  A parameter may be unset by calling `parampl' with a value
  4805. argument of NULL.
  4806.    If at Plotter creation time a parameter is *not* set, its default
  4807. value will be used, unless there is an environment variable of the same
  4808. name, in which case the value of that environment variable will be used.
  4809. This rule increases run-time flexibility: an application programmer may
  4810. allow non-critical driver parameters to be specified by the user via
  4811. environment variables.
  4812.    The following are the currently recognized parameters (unrecognized
  4813. ones are ignored).  The most important ones are `DISPLAY' and
  4814. `BITMAPSIZE', which affect X Plotters, and `PAGESIZE', which affects
  4815. Postscript, Fig, and HP-GL Plotters.  These three parameters are listed
  4816. first and the others alphabetically.  Many of the parameters, such as
  4817. the several whose names begin with "HPGL", affect only a single type of
  4818. Plotter.
  4819. `DISPLAY'
  4820.      (Default NULL.)  The X Window System display on which the graphics
  4821.      display will be popped up, as an X window.  This is relevant only
  4822.      to X Plotters.
  4823. `BITMAPSIZE'
  4824.      (Default "570x570".)  The size of the graphics display in terms of
  4825.      pixels.  This is relevant only to X Plotters.  If this parameter
  4826.      is not set, its value will automatically be taken from the
  4827.      X resource `Xplot.geometry'.  This is for backward compatibility.
  4828. `PAGESIZE'
  4829.      (Default "letter".)  The size of the page on which the graphics
  4830.      display will be positioned.  This is relevant only to Postscript,
  4831.      Fig, and HP-GL Plotters.  "letter" means an 8.5in by 11in page.
  4832.      Any ISO page size in the range "a0"..."a4" or ANSI page size in
  4833.      the range "a"..."e" may be specified ("letter" is an alias for "a"
  4834.      and "tabloid" is an alias for "b").  "legal" and "ledger" are
  4835.      recognized page sizes also.
  4836.      For Postscript Plotters, the graphics display will be a square
  4837.      region centered on the specified page and occupying its full
  4838.      width.  For Fig Plotters, the graphics display will be a square
  4839.      region located in the upper left corner of an `xfig' display, with
  4840.      width equal to the width of the specified page.  For HP-GL
  4841.      Plotters, fine control over the positioning of the graphics
  4842.      display on the page may be accomplished by setting the
  4843.      `HPGL_XOFFSET' and `HPGL_YOFFSET' parameters.
  4844. `BG_COLOR'
  4845.      (Default "white".)  The initial background color of the graphics
  4846.      display, when drawing each page of graphics.  This is relevant to
  4847.      X Plotters and X Drawable Plotters, although for the latter, the
  4848.      background color shows up only if `erase' is invoked.  The
  4849.      background color may be changed at any later time by invoking the
  4850.      bgcolor (or bgcolorname) and erase operations.  An unrecognized
  4851.      color name sets the background color to the default.  For
  4852.      information on what names are recognized, see *Note Color Names::.
  4853. `HPGL_ASSIGN_COLORS'
  4854.      (Default "no".)  Relevant only to HP-GL Plotters, and only if the
  4855.      value of `HPGL_VERSION' is "2".  "no" means to draw with a fixed
  4856.      set of pens, specified by setting the `HPGL_PENS' parameter.  "yes"
  4857.      means that pen colors will not restricted to the palette specified
  4858.      in `HPGL_PENS': colors will be assigned to "logical pens" in the
  4859.      range #1...#31, as needed.  Other than color LaserJet printers and
  4860.      DesignJet plotters, not many HP-GL/2 devices allow the assignment
  4861.      of colors to logical pens.  So this parameter should be used with
  4862.      caution.
  4863. `HPGL_OPAQUE_MODE'
  4864.      (Default "yes".)  Relevant only to HP-GL Plotters, and only if the
  4865.      value of `HPGL_VERSION' is "2".  "yes" means that the HP-GL/2
  4866.      output device should be switched into opaque mode, rather than
  4867.      transparent mode.  This allows objects to be filled with opaque
  4868.      white and other opaque colors.  It also allows the drawing of
  4869.      visible white lines, which by convention are drawn with pen #0.
  4870.      Not all HP-GL/2 devices support opaque mode or the use of pen #0
  4871.      to draw visible white lines.  In particular, HP-GL/2 pen plotters
  4872.      do not.  Some older HP-GL/2 devices reportedly malfunction if
  4873.      asked to switch into opaque mode.  If the output of an HP-GL
  4874.      Plotter is to be sent to such a device, a "no" value is
  4875.      recommended.
  4876. `HPGL_PENS'
  4877.      (Default "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan"
  4878.      if the value of `HPGL_VERSION' is "1.5" or "2" and "1=black" if the
  4879.      value of `HPGL_VERSION' is "1".  Relevant only to HP-GL Plotters.
  4880.      The set of available pens; the format should be self-explanatory.
  4881.      The color for any pen in the range #1...#31 may be specified.  For
  4882.      information on what color names are recognized, see *Note Color
  4883.      Names::.  Pen #1 must always be present, though it need not be
  4884.      black.  Any other pen in the range #1...#31 may be omitted.
  4885. `HPGL_ROTATE'
  4886.      (Default "0".)  Relevant only to HP-GL Plotters.  The angle, in
  4887.      degrees, by which the graphics display should be rotated on the
  4888.      page relative to the default orientation.  Recognized values are
  4889.      "0", "90", "180", and "270"; "no" and "yes" are equivalent to
  4890.      "0" and "90" respectively.  This parameter is provided to
  4891.      facilitate switching between portrait and landscape orientations.
  4892.      For HP-GL output devices this is frequently a concern, since some
  4893.      HP-GL devices ("plotters") draw with a default landscape
  4894.      orientation, and others ("printers") draw with a default portrait
  4895.      orientation.  "180" and "270" are supported only if `HPGL_VERSION'
  4896.      is "2".
  4897. `HPGL_VERSION'
  4898.      (Default "2".)  Relevant only to HP-GL Plotters.  "1" means that
  4899.      the output should be generic HP-GL, "1.5" means that the output
  4900.      should be suitable for the HP7550A graphics plotter and the
  4901.      HP758x, HP7595A and HP7596A drafting plotters (HP-GL with some
  4902.      HP-GL/2 extensions), and "2" means that the output should be
  4903.      modern HP-GL/2.  If the version is "1" or "1.5" then the only
  4904.      available fonts will be vector fonts, and all paths will be drawn
  4905.      with a default width.  Additionally, if the version is "1" then
  4906.      the filling of arbitrary paths will not be supported (circles and
  4907.      rectangles aligned with the coordinate axes may be filled).
  4908. `HPGL_XOFFSET'
  4909.      (Default "0.0cm".)  Relevant only to HP-GL Plotters.  An
  4910.      adjustment, in the x direction, of the position of the graphics
  4911.      display on the page.  It may be specified in centimeters,
  4912.      millimeters, or inches.  For example, an offset could be specified
  4913.      as "2cm" or "1.2in".
  4914. `HPGL_YOFFSET'
  4915.      (Default "0.0cm".)  Relevant only to HP-GL Plotters.  An
  4916.      adjustment, in the y direction, of the position of the graphics
  4917.      display on the page.
  4918. `MAX_LINE_LENGTH'
  4919.      (Default "500".)  The maximum number of points that a path may
  4920.      contain, before it is flushed to the display device.  If this
  4921.      flushing occurs, the path will be split into two or more
  4922.      sub-paths, though the splitting should not be noticeable.
  4923.      Splitting will not be performed if the path is filled.
  4924.      This parameter is relevant to X, X Drawable, Postscript, Fig, and
  4925.      HP-GL Plotters.  The reason for splitting long paths is that some
  4926.      display devices (e.g., old Postscript printers and HP-GL plotters)
  4927.      have limited buffer sizes.  It is not relevant to Tektronix or
  4928.      Metafile Plotters, since they draw paths in real time and have no
  4929.      buffer limitations.
  4930. `META_PORTABLE'
  4931.      (Default "no".)  Relevant only to Metafile Plotters.  "yes" means
  4932.      that the output should be in a portable (human-readable) version
  4933.      of the metafile format, rather than the default (binary) version.
  4934.      *Note Metafiles::.
  4935. `TERM'
  4936.      (Default NULL.)  Relevant only to Tektronix Plotters.  If the
  4937.      value is `xterm', `xterms', or `kterm', it is taken as a sign that
  4938.      the current application is running in an X Window System VT100
  4939.      terminal emulator: an `xterm'.  Before drawing graphics, a
  4940.      Tektronix Plotter will emit an escape sequence that causes the
  4941.      terminal emulator's auxiliary Tektronix window, which is normally
  4942.      hidden, to pop up.  After the graphics are drawn, an escape
  4943.      sequence that returns control to the original VT100 window will be
  4944.      emitted.  The Tektronix window will remain on the screen.
  4945.      If the value of is `kermit', `ansi.sys', `ansissys', `ansi.sysk',
  4946.      or `ansisysk', it is taken as a sign that the current application
  4947.      is running in the VT100 terminal emulator provided by the MS-DOS
  4948.      version of `kermit'.  Before drawing graphics, a Tektronix Plotter
  4949.      will emit an escape sequence that switches the terminal emulator
  4950.      to Tektronix mode.  Also, some of the Tektronix control codes
  4951.      emitted by the Plotter will be `kermit'-specific.  There will be a
  4952.      limited amount of color support, which is not normally the case
  4953.      (the 16 `ansi.sys' colors will be supported).  After drawing
  4954.      graphics, the Plotter will emit an escape sequence that returns
  4955.      the emulator to VT100 mode.  The key sequence `ALT minus' may be
  4956.      employed manually within `kermit' to switch between the two modes.
  4957. `USE_DOUBLE_BUFFERING'
  4958.      (Default "no".)  Relevant only to X Plotters and X Drawable
  4959.      Plotters.  If the value is "yes", each frame of graphics, within a
  4960.      openpl...closepl pair, is written to an off-screen buffer rather
  4961.      than to the Plotter's display.  When erase is invoked to end a
  4962.      frame, or when closepl is invoked, the contents of the off-screen
  4963.      buffer are copied to the Plotter's display, pixel by pixel.  This
  4964.      double buffering scheme is useful in creating the illusion of
  4965.      smooth animation.  A value of "fast" rather than "yes" requests
  4966.      that an X Plotter use server-supported double buffering.
  4967.      If "fast" is set, the X Plotter will attempt to use the standard
  4968.      DBE and MBX extensions to the X11 protocol to communicate with the
  4969.      display.  If either of these two options is available, it may
  4970.      yield much faster animation; on high-end graphics hardware,
  4971.      at least.  If the extensions are unavailable, "fast" means the
  4972.      same as "yes".
  4973. `VANISH_ON_DELETE'
  4974.      (Default "no".)  Relevant only to X Plotters.  If the value is
  4975.      "yes", when a Plotter is deleted, the window or windows that it
  4976.      has popped up will vanish.  Otherwise, each such window will
  4977.      remain on the screen until it is removed by the user (by typing
  4978.      `q' in it, or by clicking with a mouse).
  4979. `XDRAWABLE_COLORMAP'
  4980.      (Default NULL.)  Relevant only to X Drawable Plotters.  If the
  4981.      value is non-NULL, it should be a `Colormap *', a pointer to a
  4982.      colormap from which colors should be allocated.  NULL indicates
  4983.      that the colormap to be used should be the default colormap of the
  4984.      default screen of the X display.
  4985. `XDRAWABLE_DISPLAY'
  4986.      (Default NULL.)  Relevant only to X Drawable Plotters.  The value
  4987.      should be a `Display *', a pointer to the X display with which the
  4988.      drawable(s) to be drawn in are associated.
  4989. `XDRAWABLE_DRAWABLE1'
  4990. `XDRAWABLE_DRAWABLE2'
  4991.      (Default NULL.)  Relevant only to X Drawable Plotters.  If set, the
  4992.      value of each of these parameters should be a `Drawable *', a
  4993.      pointer to a drawable to be drawn in.  A `drawable' is either a
  4994.      window or a pixmap.  At the time an X Drawable Plotter is created,
  4995.      at least one of the two parameters must be set.
  4996.      X Drawable Plotters support simultaneous drawing in two drawables
  4997.      because it is often useful to be able to draw graphics
  4998.      simultaneously in both an X window and its background pixmap.  If
  4999.      two drawables are specified, they must have the same dimensions
  5000.      and depth, and be associated with the same screen of the X display.
  5001. File: plotutils.info,  Node: Appendices,  Prev: libplot,  Up: Top
  5002.    The following appendices contain miscellaneous information on the
  5003. GNU plotting utilities.
  5004. * Menu:
  5005. * Text and Markers::    Text fonts, text strings, and marker symbols
  5006. * Color Names::         Specifying colors by name
  5007. * Metafiles::           The device-independent GNU metafile format
  5008. * Auxiliary Software::  How to obtain auxiliary software
  5009. * Acknowledgements::    The Contributors
  5010. File: plotutils.info,  Node: Text and Markers,  Next: Color Names,  Prev: Appendices,  Up: Appendices
  5011. Fonts, Strings, and Symbols
  5012. ***************************
  5013.    The `libplot' vector graphics library and applications built on it,
  5014. such as `graph' and `plot', can draw text strings in a wide variety of
  5015. fonts.  Text strings may include characters from more than one font in
  5016. a typeface, and may include superscripts, subscripts, and square roots.
  5017. A wide variety of plotting symbols can also be drawn.  The following
  5018. sections explain how to use these features.
  5019. * Menu:
  5020. * Text Fonts::          Available text fonts
  5021. * Text Fonts in X::     Available text fonts in the X Window System
  5022. * Text String Format::  Text string formatting (with escape sequences)
  5023. * Marker Symbols::      Available marker symbols
  5024. File: plotutils.info,  Node: Text Fonts,  Next: Text Fonts in X,  Prev: Text and Markers,  Up: Text and Markers
  5025. Available text fonts
  5026. ====================
  5027.    The `libplot' library and applications built on it, such as `graph'
  5028. and `plot', can use many fonts.  These include 22 Hershey vector fonts,
  5029. 35 Postscript fonts, and 45 PCL 5 fonts.  We call these 102 fonts the
  5030. `built-in' fonts.  The Hershey fonts are constructed from stroked
  5031. characters digitized c. 1967 by Dr.  Allen V. Hershey at the U.S. Naval
  5032. Surface Weapons Center in Dahlgren, VA.  The 35 Postscript fonts are
  5033. the outline fonts resident in all modern Postscript printers, and the
  5034. 45 PCL 5 fonts are the outline fonts resident in modern Hewlett-Packard
  5035. LaserJet printers and plotters.  (The old LaserJet III, which was
  5036. Hewlett-Packard's first PCL 5 printer, supported only 8 of the 45.)
  5037.    The Hershey fonts can be used by all types of Plotter supported by
  5038. `libplot', and the Postscript fonts can be used by all types of Plotter
  5039. except HP-GL and Tektronix.  So all variants of `graph' can use the
  5040. Hershey fonts, and all variants of `graph' except `graph -T hpgl' and
  5041. `graph -T tek' can use the Postscript fonts.  The PCL 5 fonts can be
  5042. used by HP-GL Plotters and `graph -T hpgl'.  X Plotters and `graph
  5043. -T X' are not restricted to the built-in fonts.  They can use any
  5044. X Window System font.
  5045.    The `plotfont' utility, which accepts the `-T' option, will print a
  5046. character map of any font that is available on the specified output
  5047. device.  *Note plotfont::.
  5048.    For the purpose of plotting text strings (see *Note Text String
  5049. Format::), the 102 built-in fonts are divided into typefaces.  The 22
  5050. Hershey fonts are divided into typefaces as follows.
  5051.    * HersheySerif
  5052.        1. HersheySerif
  5053.        2. HersheySerif-Italic
  5054.        3. HersheySerif-Bold
  5055.        4. HersheySerif-BoldItalic
  5056.        5. HersheyCyrillic
  5057.        6. HersheyCyrillic-Oblique
  5058.        7. HersheyEUC
  5059.    * HersheySans
  5060.        1. HersheySans
  5061.        2. HersheySans-Oblique
  5062.        3. HersheySans-Bold
  5063.        4. HersheySans-BoldOblique
  5064.    * HersheyScript
  5065.        1. HersheyScript
  5066.        2. HersheyScript
  5067.        3. HersheyScript-Bold
  5068.        4. HersheyScript-Bold
  5069.    * HersheyGothicEnglish
  5070.    * HersheyGothicGerman
  5071.    * HersheyGothicItalian
  5072.    * HersheySerifSymbol
  5073.        1. HersheySerifSymbol
  5074.        2. HersheySerifSymbol-Oblique
  5075.        3. HersheySerifSymbol-Bold
  5076.        4. HersheySerifSymbol-BoldOblique
  5077.    * HersheySansSymbol
  5078.        1. HersheySansSymbol
  5079.        2. HersheySansSymbol-Oblique
  5080. The three HersheyGothic fonts are singletons: each is font #1 of its own
  5081. typeface.  The symbol fonts contain Greek characters and mathematical
  5082. symbols, and play a special role.  By convention, each Hershey typeface
  5083. contains a symbol font (HersheySerifSymbol or HersheySansSymbol, as
  5084. appropriate) as font #0.
  5085.    The 35 Postscript fonts are divided into typefaces as follows.
  5086.    * Helvetica
  5087.        1. Helvetica
  5088.        2. Helvetica-Oblique
  5089.        3. Helvetica-Bold
  5090.        4. Helvetica-BoldOblique
  5091.    * Helvetica-Narrow
  5092.        1. Helvetica-Narrow
  5093.        2. Helvetica-Narrow-Oblique
  5094.        3. Helvetica-Narrow-Bold
  5095.        4. Helvetica-Narrow-BoldOblique
  5096.    * Times
  5097.        1. Times-Roman
  5098.        2. Times-Italic
  5099.        3. Times-Bold
  5100.        4. Times-BoldItalic
  5101.    * AvantGarde
  5102.        1. AvantGarde-Book
  5103.        2. AvantGarde-BookOblique
  5104.        3. AvantGarde-Demi
  5105.        4. AvantGarde-DemiOblique
  5106.    * Bookman
  5107.        1. Bookman-Light
  5108.        2. Bookman-LightItalic
  5109.        3. Bookman-Demi
  5110.        4. Bookman-DemiItalic
  5111.    * Courier
  5112.        1. Courier
  5113.        2. Courier-Oblique
  5114.        3. Courier-Bold
  5115.        4. Courier-BoldOblique
  5116.    * NewCenturySchlbk
  5117.        1. NewCenturySchlbk-Roman
  5118.        2. NewCenturySchlbk-Italic
  5119.        3. NewCenturySchlbk-Bold
  5120.        4. NewCenturySchlbk-BoldItalic
  5121.    * Palatino
  5122.        1. Palatino-Roman
  5123.        2. Palatino-Italic
  5124.        3. Palatino-Bold
  5125.        4. Palatino-BoldItalic
  5126.    * ZapfChancery-MediumItalic
  5127.    * ZapfDingbats
  5128.    * Symbol
  5129. The two Zapf fonts are singletons: each is font #1 of its own typeface.
  5130. The Symbol font plays a special role.  By convention, each Postscript
  5131. typeface contains the Symbol font as font #0.
  5132.    The 45 PCL 5 fonts are divided into typefaces as follows.
  5133.    * Univers
  5134.        1. Univers
  5135.        2. Univers-Oblique
  5136.        3. Univers-Bold
  5137.        4. Univers-BoldOblique
  5138.    * UniversCondensed
  5139.        1. UniversCondensed
  5140.        2. UniversCondensed-Oblique
  5141.        3. UniversCondensed-Bold
  5142.        4. UniversCondensed-BoldOblique
  5143.    * CGTimes
  5144.        1. CGTimes-Roman
  5145.        2. CGTimes-Italic
  5146.        3. CGTimes-Bold
  5147.        4. CGTimes-BoldItalic
  5148.    * Albertus
  5149.        1. AlbertusMedium
  5150.        2. AlbertusMedium
  5151.        3. AlbertusExtraBold
  5152.        4. AlbertusExtraBold
  5153.    * AntiqueOlive
  5154.        1. AntiqueOlive
  5155.        2. AntiqueOlive-Italic
  5156.        3. AntiqueOlive-Bold
  5157.    * Arial
  5158.        1. Arial-Roman
  5159.        2. Arial-Italic
  5160.        3. Arial-Bold
  5161.        4. Arial-BoldItalic
  5162.    * ClarendonCondensed
  5163.    * Coronet
  5164.    * Courier
  5165.        1. Courier
  5166.        2. Courier-Italic
  5167.        3. Courier-Bold
  5168.        4. Courier-BoldItalic
  5169.    * Garamond
  5170.        1. Garamond
  5171.        2. Garamond-Italic
  5172.        3. Garamond-Bold
  5173.        4. Garamond-BoldItalic
  5174.    * LetterGothic
  5175.        1. LetterGothic-Roman
  5176.        2. LetterGothic-Italic
  5177.        3. LetterGothic-Bold
  5178.        4. LetterGothic-BoldItalic
  5179.    * Marigold
  5180.    * CGOmega
  5181.        1. CGOmega-Roman
  5182.        2. CGOmega-Italic
  5183.        3. CGOmega-Bold
  5184.        4. CGOmega-BoldItalic
  5185.    * TimesNewRoman
  5186.        1. TimesNewRoman
  5187.        2. TimesNewRoman-Italic
  5188.        3. TimesNewRoman-Bold
  5189.        4. TimesNewRoman-BoldItalic
  5190.    * Wingdings
  5191.    * Symbol
  5192. The ClarendonCondensed, Coronet, Marigold, and Wingdings fonts are
  5193. singletons: each is font #1 of its own typeface.  The Symbol font plays
  5194. a special role.  By convention, each PCL 5 typeface contains the Symbol
  5195. font as font #0.
  5196.    As you can see from the three preceding tables, our convention is
  5197. that in any typeface with more than a single font, font #1 is the normal
  5198. font, font #2 is italic or oblique, font #3 is bold, and font #4 is bold
  5199. italic or bold oblique.  Additional variants (if any) are numbered #5
  5200. and higher.
  5201.    Of the above 102 built-in fonts, all except for the four Symbol
  5202. fonts, HersheyCyrillic, HersheyCyrillic-Oblique, HersheyEUC,
  5203. ZapfDingbats, and Wingdings are ISO-8859-1 fonts.  This means that they
  5204. use the ISO-Latin-1 encoding, which is a superset of ASCII.  The four
  5205. Symbol fonts use a special encoding, since they consist of Greek
  5206. characters and mathematical symbols.  The Symbol encoding and the
  5207. encoding used by the ZapfDingbats font are documented in the
  5208. `Postscript Language Reference Manual'.
  5209.    The HersheyCyrillic and HersheyCyrillic-Oblique fonts use an encoding
  5210. called KOI8-R, a superset of ASCII which has become the de facto
  5211. standard for Unix and networking applications in the former Soviet
  5212. Union.  Insofar as printable ASCII characters go, they resemble the
  5213. HersheySerif fonts.  But their `8-bit' characters are different.  The
  5214. byte range 0xc0...0xdf contains lower-case Cyrillic characters and the
  5215. byte range 0xe0...0xff contains upper case Cyrillic characters.
  5216. Additional Cyrillic characters are located at 0xa3 and 0xb3.  For more
  5217. on the encoding scheme, see the official KOI8-R Web page (http://www.nagual.pp.ru/~ache/koi8.html) and the document known as Internet RFC
  5218. 1489.
  5219.    The HersheyEUC font is used for displaying Japanese.  EUC stands for
  5220. `extended Unix code', which is a scheme for encoding Japanese, and also
  5221. other character sets (e.g., Greek and Cyrillic) as multibyte character
  5222. strings.  The format of EUC strings is explained in Ken Lunde's
  5223. `Understanding Japanese Information Processing' (O'Reilly, 1993), which
  5224. contains much additional information on Japanese text processing.  See
  5225. also his on-line supplement (http://www.ora.com/people/authors/lunde/cjk_inf.html).
  5226.    In the HersheyEUC font, characters in the printable ASCII range,
  5227. 0x20...0x7e, are similar to US ASCII (they are `JIS Roman', an ASCII
  5228. variant standardized by the Japanese Industrial Standards Committee).
  5229. Each successive pair of bytes in the `0xa1'...`0xfe' range defines a
  5230. single character in the JIS X0208 standard.  The characters in the JIS
  5231. X0208 standard include Japanese syllabic characters (Hiragana and
  5232. Katakana), ideographic characters (Kanji), Roman, Greek, and Cyrillic
  5233. alphabets, punctuation marks, and miscellaneous symbols.  For example,
  5234. the JIS X0208 standard indexes the 83 Hiragana as `0x2421'...`0x2453'.
  5235. To obtain the EUC code for any JIS X0208 character, you would add
  5236. `0x80' to each byte (i.e., `set the high bit' on each byte).  So the
  5237. first of the 83 Hiragana (`0x2421') would be encoded as the successive
  5238. pair of bytes `0xa4' and `0xa1'.
  5239.    The implementation of the JIS X0208 standard in the HersheyEUC font
  5240. is based on Dr. Hershey's digitizations, and is complete enough to be
  5241. useful.  All Hiragana and Katakana are available, though the little-used
  5242. `half-width Katakana' are not supported.  Also, 603 frequently used
  5243. Kanji are available.  The Hiragana, the Katakana, and the available
  5244. Kanji all have the same width.  The file `kanji.doc', which on most
  5245. systems is installed in `/usr/share/libplot' or
  5246. `/usr/local/share/libplot', lists the 603 available Kanji.  Each JIS
  5247. X0208 character that is unavailable will be drawn as an `undefined
  5248. character' glyph (several horizontal lines).
  5249.    To what extent do the fonts supported by `libplot' contain
  5250. ligatures?  The 35 Postscript fonts and 45 PCL 5 fonts, as implemented
  5251. in `libplot', do not contain ligatures.  However, four of the 22
  5252. Hershey fonts contain ligatures.  The character combinations "fi",
  5253. "ff", "fl", "ffi", and "ffl" are automatically drawn as ligatures in
  5254. HersheySerif and HersheySerif-Italic.  (Also in the HersheyCyrillic
  5255. fonts and HersheyEUC, since insofar as printable ASCII characters are
  5256. concerned, they are identical [or almost identical] to HersheySerif.)
  5257. In addition, "tz" and "ch" are ligatures in HersheyGothicGerman.  The
  5258. German double-s character `ss', which is called an `eszet', is not
  5259. treated as a ligature in any font.  To obtain an eszet, you must either
  5260. request one with the escape sequence "\ss" (*note Text String
  5261. Format::.), or, if you have an 8-bit keyboard, type an eszet explicitly.
  5262. File: plotutils.info,  Node: Text Fonts in X,  Next: Text String Format,  Prev: Text Fonts,  Up: Text and Markers
  5263. Available text fonts for the X Window System
  5264. ============================================
  5265.    The plotting utilities `graph -T X' and `plot -T X', and the
  5266. `libplot' library that they are built on, can draw text on an X Window
  5267. System display in a wide variety of fonts.  This includes the 22
  5268. built-in Hershey vector fonts.  They can use the 35 built-in Postscript
  5269. fonts too, if those fonts are available on the X display.  Most
  5270. releases of the plotting utilities include freely distributable
  5271. versions of the 35 Postscript fonts, in Type 1 format, that are easily
  5272. installed on any X display.
  5273.    In fact, the plotting utilities can use most fonts that are
  5274. available on the current X display.  This includes all scalable fonts
  5275. that have a so-called XLFD (X Logical Font Description) name.  For
  5276. example, the "CharterBT-Roman" font is available on many X displays.
  5277. It has a formal XLFD name, namely
  5278. "-bitstream-charter-medium-r-normal-0-0-0-0-p-0-iso8859-1".  The
  5279. plotting utilities would refer to it as "charter-medium-r-normal".  The
  5280. command
  5281.      echo 0 0 1 1 2 0 | graph -T X -F charter-medium-r-normal
  5282. would draw a plot in a popped-up X window, in which all axis ticks are
  5283. labeled in this font.
  5284.    You may determine which fonts are available on an X display by using
  5285. the `xlsfonts' command.  Fonts whose names end in
  5286. "-0-0-0-0-p-0-iso8859-1" or "-0-0-0-0-m-0-iso8859-1" are scalable
  5287. ISO-Latin-1 fonts that can be used by `libplot''s X Plotters and by
  5288. `graph -T X' and `plot -T X'.  The two sorts of font are variable-width
  5289. and fixed-width fonts, respectively.  Fonts whose names end in
  5290. "iso8859-2", etc., and "adobe-fontspecific", may also be used, even
  5291. though they do not employ the standard ISO-Latin-1 encoding.
  5292.    The escape sequences that provide access to the non-ASCII `8-bit'
  5293. characters in the built-in ISO-Latin-1 fonts may be employed when using
  5294. any ISO-Latin-1 X Window System font.  For more on escape sequences,
  5295. see *Note Text String Format::.  As an example, "\Po" will yield the
  5296. British pounds sterling symbol `#'.  The command
  5297.      echo 0 0 1 1 | graph -T X -F charter-medium-r-normal -L "A \Po1 Plot"
  5298. shows how this symbol could be used in a graph label.  In the same way,
  5299. the escape sequences that provide access to mathematical symbols and
  5300. Greek characters may be employed when using any X Window System font,
  5301. whether or not it is an ISO-Latin-1 font.
  5302.    The plotting utilities, including `graph', support a `--bitmap-size'
  5303. option.  It is meaningful only if the `-T X' option is used, since it
  5304. sets the size of the popped-up X Window.  You may use it to obtain some
  5305. interesting visual effects.  `graph' assumes that it is drawing in a
  5306. square region, so if you use the `--bitmap-size 800x400' option, your
  5307. plot will be scaled anisotropically, by a larger factor in the
  5308. horizontal direction than in the vertical direction.  The fonts in the
  5309. plot will be scaled in the same way.  Actually, this requires a modern
  5310. (X11R6) display.  If your X display cannot scale a font, a default
  5311. scalable font (such as "HersheySerif") will be substituted.
  5312. File: plotutils.info,  Node: Text String Format,  Next: Marker Symbols,  Prev: Text Fonts in X,  Up: Text and Markers
  5313. Text string format and escape sequences
  5314. =======================================
  5315.    Text strings that are drawn by `libplot', and by such applications
  5316. as `graph' and `plot' that are built on `libplot', must consist of
  5317. printable characters.  No embedded control characters, such as newlines
  5318. or carriage returns, are allowed.  Technically, a character is
  5319. `printable' if it comes from either of the two byte ranges 0x20...0x7e
  5320. and 0xa0...0xff.  The former is the printable ASCII range and the
  5321. latter is the printable `8-bit' range.
  5322.    Text strings may, however, include embedded `escape sequences' that
  5323. shift the font, append subscripts or superscripts, or include non-ASCII
  5324. characters and mathematical symbols.  As a consequence, the axis labels
  5325. on a plot prepared with `graph' may include such features.
  5326.    The format of the escape sequences should look familiar to anyone
  5327. who is familiar with the TeX or `groff' document formatters.  Each
  5328. escape sequence consists of three characters: a backslash and two
  5329. additional characters.  The most frequently used escape sequences are as
  5330. follows.
  5331. "\sp"
  5332.      start superscript mode
  5333. "\ep"
  5334.      end superscript mode
  5335. "\sb"
  5336.      start subscript mode
  5337. "\eb"
  5338.      end subscript mode
  5339. "\mk"
  5340.      mark location
  5341. "\rt"
  5342.      return to marked location
  5343. For example, the string "x\sp2\ep" would be interpreted as `x squared'.
  5344. Subscripts on subscripts, etc., are allowed.  Subscripts and
  5345. superscripts may be vertically aligned by judicious use of the "\mk" and
  5346. "\rt" escape sequences.  For example, "a\mk\sbi\eb\rt\sp2\ep" produces
  5347. "a sub i squared", with the exponent `2' placed immediately above the
  5348. subscript.
  5349.    There are also escape sequences that switch from font to font within
  5350. a typeface.  For an enumeration of the fonts within each typeface, see
  5351. *Note Text Fonts::.  Suppose for example that the current font is
  5352. Times-Roman, which is font #1 in the `Times' typeface.  The string "A
  5353. \f2very\f1 well labeled axis" would be a string in which the word `very'
  5354. appears in Times-Italic rather than Times-Roman.  That is because
  5355. Times-Italic is the #2 font in the typeface.  Font-switching escape
  5356. sequences are of the form "\fN", where N is the number of the font to
  5357. be switched to, in the current font.  There is currently no support for
  5358. switching between fonts in different typefaces.
  5359.    There are also a few escape sequences for horizontal shifts, which
  5360. are useful for improving horizontal alignment, such as when shifting
  5361. between fonts.  "\r1", "\r2", "\r4", "\r6", "\r8" are escape sequences
  5362. that shift right by 1 em, 1/2 em, 1/4 em, 1/6 em, and 1/8 em,
  5363. respectively.  "\l1", "\l2", "\l4", "\l6", "\l8" are similar, but shift
  5364. left instead of right.  "A \f2very\r8\f1 well labeled axis" would look
  5365. better than "A \f2very\f1 well labeled axis".
  5366.    Square roots are handled with the aid of a special pair of escape
  5367. sequences, together with the "\mk" and "\rt" sequences discussed above.
  5368. A square root symbol is begun with "\sr", and continued arbitrarily far
  5369. to the right with the overbar (`run') escape sequence, "\rn".  For
  5370. example, the string "\sr\mk\rn\rn\rtab" would be plotted as `the square
  5371. root of ab'.  To adjust the length of the overbar, you may need to
  5372. experiment with the number of times "\rn" appears.
  5373.    To underline a string, you would use "\ul", the underline escape
  5374. sequence, one or more times.  The "\mk"..."\rt" trick would be employed
  5375. in the same way.  So, for example, "\mk\ul\ul\ul\rtabc" would yield an
  5376. underlined "abc".  To adjust the length of the underline, you may need
  5377. to experiment with the number of times "\ul" appears.  You may also
  5378. need to use one or more of the abovementioned horizontal shifts.  For
  5379. example, if the "HersheySerif" font were used, "\mk\ul\ul\l8\ul\rtabc"
  5380. would yield a better underline than "\mk\ul\ul\ul\rtabc".
  5381.    Besides the preceding escape sequences, there are also escape
  5382. sequences for the printable non-ASCII characters in each of the built-in
  5383. ISO-Latin-1 fonts (which means in every built-in font, except for the
  5384. symbol fonts, the HersheyCyrillic fonts, HersheyEUC, and ZapfDingbats).
  5385. The useful non-ASCII characters include accented characters among
  5386. others.  Such `8-bit' characters, in the 0xa0...0xff byte range, may be
  5387. included directly in a text string.  But if your terminal does not
  5388. permit this, you may use the escape sequences for them instead.
  5389.    There are escape sequences for the mathematical symbols and Greek
  5390. characters in the symbol fonts, as well.  This is how the symbol fonts
  5391. are usually accessed.  Which symbol font the mathematical symbols and
  5392. Greek characters are taken from depends on whether your current font is
  5393. a Hershey font or a non-Hershey font.  They are taken from the
  5394. HersheySerifSymbol font or the HersheySansSymbol font in the former
  5395. case, and from the Symbol font in the latter.
  5396.    The following are the escape sequences that provide access to the
  5397. non-ASCII characters of the current font, provided that it is an
  5398. ISO-Latin-1 font.  Each escape sequence is followed by the position of
  5399. the corresponding character in the ISO-Latin-1 encoding (in decimal),
  5400. and the official Postscript name of the character.  Most names should be
  5401. self-explanatory.  For example, `eacute' is a lower-case `e', equipped
  5402. with an acute accent.
  5403. "\r!"
  5404.      [161] exclamdown
  5405. "\ct"
  5406.      [162] cent
  5407. "\Po"
  5408.      [163] sterling
  5409. "\Cs"
  5410.      [164] currency
  5411. "\Ye"
  5412.      [165] yen
  5413. "\bb"
  5414.      [166] brokenbar
  5415. "\sc"
  5416.      [167] section
  5417. "\ad"
  5418.      [168] dieresis
  5419. "\co"
  5420.      [169] copyright
  5421. "\Of"
  5422.      [170] ordfeminine
  5423. "\Fo"
  5424.      [171] guillemotleft
  5425. "\no"
  5426.      [172] logicalnot
  5427. "\hy"
  5428.      [173] hyphen
  5429. "\rg"
  5430.      [174] registered
  5431. "\a-"
  5432.      [175] macron
  5433. "\de"
  5434.      [176] degree
  5435. "\+-"
  5436.      [177] plusminus
  5437. "\S2"
  5438.      [178] twosuperior
  5439. "\S3"
  5440.      [179] threesuperior
  5441. "\aa"
  5442.      [180] acute
  5443. "\*m"
  5444.      [181] mu
  5445. "\ps"
  5446.      [182] paragraph
  5447. "\md"
  5448.      [183] periodcentered
  5449. "\ac"
  5450.      [184] cedilla
  5451. "\S1"
  5452.      [185] onesuperior
  5453. "\Om"
  5454.      [186] ordmasculine
  5455. "\Fc"
  5456.      [187] guillemotright
  5457. "\14"
  5458.      [188] onequarter
  5459. "\12"
  5460.      [189] onehalf
  5461. "\34"
  5462.      [190] threequarters
  5463. "\r?"
  5464.      [191] questiondown
  5465. "\`A"
  5466.      [192] Agrave
  5467. "\'A"
  5468.      [193] Aacute
  5469. "\^A"
  5470.      [194] Acircumflex
  5471. "\~A"
  5472.      [195] Atilde
  5473. "\:A"
  5474.      [196] Adieresis
  5475. "\oA"
  5476.      [197] Aring
  5477. "\AE"
  5478.      [198] AE
  5479. "\,C"
  5480.      [199] Ccedilla
  5481. "\`E"
  5482.      [200] Egrave
  5483. "\'E"
  5484.      [201] Eacute
  5485. "\^E"
  5486.      [202] Ecircumflex
  5487. "\:E"
  5488.      [203] Edieresis
  5489. "\`I"
  5490.      [204] Igrave
  5491. "\'I"
  5492.      [205] Iacute
  5493. "\^I"
  5494.      [206] Icircumflex
  5495. "\:I"
  5496.      [207] Idieresis
  5497. "\-D"
  5498.      [208] Eth
  5499. "\~N"
  5500.      [209] Ntilde
  5501. "\'O"
  5502.      [210] Ograve
  5503. "\'O"
  5504.      [211] Oacute
  5505. "\^O"
  5506.      [212] Ocircumflex
  5507. "\~O"
  5508.      [213] Otilde
  5509. "\:O"
  5510.      [214] Odieresis
  5511. "\mu"
  5512.      [215] multiply
  5513. "\/O"
  5514.      [216] Oslash
  5515. "\`U"
  5516.      [217] Ugrave
  5517. "\'U"
  5518.      [218] Uacute
  5519. "\^U"
  5520.      [219] Ucircumflex
  5521. "\:U"
  5522.      [220] Udieresis
  5523. "\'Y"
  5524.      [221] Yacute
  5525. "\TP"
  5526.      [222] Thorn
  5527. "\ss"
  5528.      [223] germandbls
  5529. "\`a"
  5530.      [224] agrave
  5531. "\'a"
  5532.      [225] aacute
  5533. "\^a"
  5534.      [226] acircumflex
  5535. "\~a"
  5536.      [227] atilde
  5537. "\:a"
  5538.      [228] adieresis
  5539. "\oa"
  5540.      [229] aring
  5541. "\ae"
  5542.      [230] ae
  5543. "\,c"
  5544.      [231] ccedilla
  5545. "\`e"
  5546.      [232] egrave
  5547. "\'e"
  5548.      [233] eacute
  5549. "\^e"
  5550.      [234] ecircumflex
  5551. "\:e"
  5552.      [235] edieresis
  5553. "\`i"
  5554.      [236] igrave
  5555. "\'i"
  5556.      [237] iacute
  5557. "\^i"
  5558.      [238] icircumflex
  5559. "\:i"
  5560.      [239] idieresis
  5561. "\Sd"
  5562.      [240] eth
  5563. "\~n"
  5564.      [241] ntilde
  5565. "\`o"
  5566.      [242] ograve
  5567. "\'o"
  5568.      [243] oacute
  5569. "\^o"
  5570.      [244] ocircumflex
  5571. "\~o"
  5572.      [245] otilde
  5573. "\:o"
  5574.      [246] odieresis
  5575. "\di"
  5576.      [247] divide
  5577. "\/o"
  5578.      [248] oslash
  5579. "\`u"
  5580.      [249] ugrave
  5581. "\'u"
  5582.      [250] uacute
  5583. "\^u"
  5584.      [251] ucircumflex
  5585. "\:u"
  5586.      [252] udieresis
  5587. "\'y"
  5588.      [253] yacute
  5589. "\Tp"
  5590.      [254] thorn
  5591. "\:y"
  5592.      [255] ydieresis
  5593.    The following are the escape sequences that provide access to
  5594. mathematical symbols and Greek characters in the current symbol font,
  5595. whether HersheySerifSymbol or HersheySansSymbol (for Hershey fonts) or
  5596. Symbol (for Postscript fonts).  Each escape sequence is followed by the
  5597. position (in octal) of the corresponding character in the symbol
  5598. encoding, and the official Postscript name of the character.  Many
  5599. escape sequences and names should be self-explanatory.  "\*a" represents
  5600. a lower-case Greek alpha, for example.  For a table displaying each of
  5601. the characters below, see the `Postscript Language Reference Manual'.
  5602. "\fa"
  5603.      [0042] universal
  5604. "\te"
  5605.      [0044] existential
  5606. "\st"
  5607.      [0047] suchthat
  5608. "\**"
  5609.      [0052] asteriskmath
  5610. "\=~"
  5611.      [0100] congruent
  5612. "\*A"
  5613.      [0101] Alpha
  5614. "\*B"
  5615.      [0102] Beta
  5616. "\*X"
  5617.      [0103] Chi
  5618. "\*D"
  5619.      [0104] Delta
  5620. "\*E"
  5621.      [0105] Epsilon
  5622. "\*F"
  5623.      [0106] Phi
  5624. "\*G"
  5625.      [0107] Gamma
  5626. "\*Y"
  5627.      [0110] Eta
  5628. "\*I"
  5629.      [0111] Iota
  5630. "\+h"
  5631.      [0112] theta1
  5632. "\*K"
  5633.      [0113] Kappa
  5634. "\*L"
  5635.      [0114] Lambda
  5636. "\*M"
  5637.      [0115] Mu
  5638. "\*N"
  5639.      [0116] Nu
  5640. "\*O"
  5641.      [0117] Omicron
  5642. "\*P"
  5643.      [0120] Pi
  5644. "\*H"
  5645.      [0121] Theta
  5646. "\*R"
  5647.      [0122] Rho
  5648. "\*S"
  5649.      [0123] Sigma
  5650. "\*T"
  5651.      [0124] Tau
  5652. "\*U"
  5653.      [0125] Upsilon
  5654. "\ts"
  5655.      [0126] sigma1
  5656. "\*W"
  5657.      [0127] Omega
  5658. "\*C"
  5659.      [0130] Xi
  5660. "\*Q"
  5661.      [0131] Psi
  5662. "\*Z"
  5663.      [0132] Zeta
  5664. "\tf"
  5665.      [0134] therefore
  5666. "\pp"
  5667.      [0136] perpendicular
  5668. "\ul"
  5669.      [0137] underline
  5670. "\rx"
  5671.      [0140] radicalex
  5672. "\*a"
  5673.      [0141] alpha
  5674. "\*b"
  5675.      [0142] beta
  5676. "\*x"
  5677.      [0143] chi
  5678. "\*d"
  5679.      [0144] delta
  5680. "\*e"
  5681.      [0145] epsilon
  5682. "\*f"
  5683.      [0146] phi
  5684. "\*g"
  5685.      [0147] gamma
  5686. "\*y"
  5687.      [0150] eta
  5688. "\*i"
  5689.      [0151] iota
  5690. "\+f"
  5691.      [0152] phi1
  5692. "\*k"
  5693.      [0153] kappa
  5694. "\*l"
  5695.      [0154] lambda
  5696. "\*m"
  5697.      [0155] mu
  5698. "\*n"
  5699.      [0156] nu
  5700. "\*o"
  5701.      [0157] omicron
  5702. "\*p"
  5703.      [0160] pi
  5704. "\*h"
  5705.      [0161] theta
  5706. "\*r"
  5707.      [0162] rho
  5708. "\*s"
  5709.      [0163] sigma
  5710. "\*t"
  5711.      [0164] tau
  5712. "\*u"
  5713.      [0165] upsilon
  5714. "\+p"
  5715.      [0166] omega1
  5716. "\*w"
  5717.      [0167] omega
  5718. "\*c"
  5719.      [0170] xi
  5720. "\*q"
  5721.      [0171] psi
  5722. "\*z"
  5723.      [0172] zeta
  5724. "\ap"
  5725.      [0176] similar
  5726. "\+U"
  5727.      [0241] Upsilon1
  5728. "\fm"
  5729.      [0242] minute
  5730. "\<="
  5731.      [0243] lessequal
  5732. "\f/"
  5733.      [0244] fraction
  5734. "\if"
  5735.      [0245] infinity
  5736. "\Fn"
  5737.      [0246] florin
  5738. "\CL"
  5739.      [0247] club
  5740. "\DI"
  5741.      [0250] diamond
  5742. "\HE"
  5743.      [0251] heart
  5744. "\SP"
  5745.      [0252] spade
  5746. "\<>"
  5747.      [0253] arrowboth
  5748. "\<-"
  5749.      [0254] arrowleft
  5750. "\ua"
  5751.      [0255] arrowup
  5752. "\->"
  5753.      [0256] arrowright
  5754. "\da"
  5755.      [0257] arrowdown
  5756. "\de"
  5757.      [0260] degree
  5758. "\+-"
  5759.      [0261] plusminus
  5760. "\sd"
  5761.      [0262] second
  5762. "\>="
  5763.      [0263] greaterequal
  5764. "\mu"
  5765.      [0264] multiply
  5766. "\pt"
  5767.      [0265] proportional
  5768. "\pd"
  5769.      [0266] partialdiff
  5770. "\bu"
  5771.      [0267] bullet
  5772. "\di"
  5773.      [0270] divide
  5774. "\!="
  5775.      [0271] notequal
  5776. "\=="
  5777.      [0272] equivalence
  5778. "\~~"
  5779.      [0273] approxequal
  5780. "\.."
  5781.      [0274] ellipsis
  5782.      [0275] arrowvertex
  5783. "\an"
  5784.      [0276] arrowhorizex
  5785. "\CR"
  5786.      [0277] carriagereturn
  5787. "\Ah"
  5788.      [0300] aleph
  5789. "\Im"
  5790.      [0301] Ifraktur
  5791. "\Re"
  5792.      [0302] Rfraktur
  5793. "\wp"
  5794.      [0303] weierstrass
  5795. "\c*"
  5796.      [0304] circlemultiply
  5797. "\c+"
  5798.      [0305] circleplus
  5799. "\es"
  5800.      [0306] emptyset
  5801. "\ca"
  5802.      [0307] cap
  5803. "\cu"
  5804.      [0310] cup
  5805. "\SS"
  5806.      [0311] superset
  5807. "\ip"
  5808.      [0312] reflexsuperset
  5809. "\n<"
  5810.      [0313] notsubset
  5811. "\SB"
  5812.      [0314] subset
  5813. "\ib"
  5814.      [0315] reflexsubset
  5815. "\mo"
  5816.      [0316] element
  5817. "\nm"
  5818.      [0317] notelement
  5819. "\/_"
  5820.      [0320] angle
  5821. "\gr"
  5822.      [0321] nabla
  5823. "\rg"
  5824.      [0322] registerserif
  5825. "\co"
  5826.      [0323] copyrightserif
  5827. "\tm"
  5828.      [0324] trademarkserif
  5829. "\PR"
  5830.      [0325] product
  5831. "\sr"
  5832.      [0326] radical
  5833. "\md"
  5834.      [0327] dotmath
  5835. "\no"
  5836.      [0330] logicalnot
  5837. "\AN"
  5838.      [0331] logicaland
  5839. "\OR"
  5840.      [0332] logicalor
  5841. "\hA"
  5842.      [0333] arrowdblboth
  5843. "\lA"
  5844.      [0334] arrowdblleft
  5845. "\uA"
  5846.      [0335] arrowdblup
  5847. "\rA"
  5848.      [0336] arrowdblright
  5849. "\dA"
  5850.      [0337] arrowdbldown
  5851. "\lz"
  5852.      [0340] lozenge
  5853. "\la"
  5854.      [0341] angleleft
  5855. "\RG"
  5856.      [0342] registersans
  5857. "\CO"
  5858.      [0343] copyrightsans
  5859. "\TM"
  5860.      [0344] trademarksans
  5861. "\SU"
  5862.      [0345] summation
  5863.      [0346] parenlefttp
  5864.      [0347] parenleftex
  5865.      [0350] parenleftbt
  5866. "\lc"
  5867.      [0351] bracketlefttp
  5868.      [0352] bracketleftex
  5869. "\lf"
  5870.      [0353] bracketleftbt
  5871. "\lt"
  5872.      [0354] bracelefttp
  5873. "\lk"
  5874.      [0355] braceleftmid
  5875. "\lb"
  5876.      [0356] braceleftbt
  5877. "\bv"
  5878.      [0357] braceex
  5879. "\eu"
  5880.      [0360] euro
  5881. "\ra"
  5882.      [0361] angleright
  5883. "\is"
  5884.      [0362] integral
  5885.      [0363] integraltp
  5886.      [0364] integralex
  5887.      [0365] integralbt
  5888.      [0366] parenrighttp
  5889.      [0367] parenrightex
  5890.      [0370] parenrightbt
  5891. "\rc"
  5892.      [0371] bracketrighttp
  5893.      [0372] bracketrightex
  5894. "\rf"
  5895.      [0373] bracketrightbt
  5896. "\RT"
  5897.      [0374] bracerighttp
  5898. "\rk"
  5899.      [0375] bracerightmid
  5900. "\rb"
  5901.      [0376] bracerightbt
  5902.    Finally, there are escape sequences that apply only if the current
  5903. font is a Hershey font.  Most of these escape sequences provide access
  5904. to special symbols that belong to no font, and are accessible by no
  5905. other means.  These symbols are of two sorts: miscellaneous and
  5906. astronomical.  The escape sequences for the miscellaneous symbols are
  5907. as follows.
  5908. "\dd"
  5909.      daggerdbl
  5910. "\dg"
  5911.      dagger
  5912. "\hb"
  5913.      hbar
  5914. "\li"
  5915.      lineintegral
  5916. "\IB"
  5917.      interbang
  5918. "\Lb"
  5919.      lambdabar
  5920. "\~-"
  5921.      modifiedcongruent
  5922. "\-+"
  5923.      minusplus
  5924. "\||"
  5925.      parallel
  5926. "\s-"
  5927.      [variant form of s]
  5928. The final escape sequence in the table above, "\s-", yields a letter
  5929. rather than a symbol.  It is provided because in some Hershey fonts,
  5930. the shape of the lower-case letter `s' differs if it is the last letter
  5931. in a word.  This is the case for HersheyGothicGerman.  The German word
  5932. "besonders", for example, should be written as "besonder\s-" if it is
  5933. to be rendered correctly in this font.  The same is true for the two
  5934. Hershey symbol fonts, with their Greek alphabets (in Greek text,
  5935. lower-case final `s' is different from lower-case non-final `s').
  5936. In Hershey fonts where there is no distinction between final and
  5937. non-final `s', "s" and "\s-" are equivalent.
  5938.    The escape sequences for the astronomical symbols are listed in the
  5939. following table.  We stress that that like the preceding miscellaneous
  5940. escape sequences, they apply only if the current font is a Hershey font.
  5941. "\SO"
  5942.      sun
  5943. "\ME"
  5944.      mercury
  5945. "\VE"
  5946.      venus
  5947. "\EA"
  5948.      earth
  5949. "\MA"
  5950.      mars
  5951. "\JU"
  5952.      jupiter
  5953. "\SA"
  5954.      saturn
  5955. "\UR"
  5956.      uranus
  5957. "\NE"
  5958.      neptune
  5959. "\PL"
  5960.      pluto
  5961. "\LU"
  5962.      moon
  5963. "\CT"
  5964.      comet
  5965. "\ST"
  5966.      star
  5967. "\AS"
  5968.      ascendingnode
  5969. "\DE"
  5970.      descendingnode
  5971.    The preceding miscellaneous and astronomical symbols are not the only
  5972. special non-font symbols that can be used if the current font is a
  5973. Hershey font.  The entire library of glyphs digitized by Allen Hershey
  5974. is built into GNU `libplot'.  So text strings may include any Hershey
  5975. glyph.  Each of the available Hershey glyphs is identified by a
  5976. four-digit number.  Standard Hershey glyph #1 would be specified as
  5977. "\#H0001".  The standard Hershey glyphs range from "\#H0001" to
  5978. "\#H3999", with a number of gaps.  Some additional glyphs designed by
  5979. others appear in the "\#H4000"..."\#H4194" range.  Syllabic Japanese
  5980. characters (Kana) are located in the "\#H4195"..."\#H4399" range.
  5981.    You may order a table of nearly all the Hershey glyphs in the
  5982. "\#H0001"..."\#H3999" range from the U.S. National Technical
  5983. Information Service, at +1 703 487 4650.  Ask for item number PB251845;
  5984. the current price is about US$40.  By way of example, the string
  5985.      "\#H0744\#H0745\#H0001\#H0002\#H0003\#H0869\#H0907\#H2330\#H2331"
  5986. when drawn will display a shamrock, a fleur-de-lys, cartographic (small)
  5987. letters A, B, C, a bell, a large circle, a treble clef, and a bass
  5988. clef.  Again, this assumes that the current font is a Hershey font.
  5989.    You may also use Japanese syllabic characters (Hiragana and Katakana)
  5990. and ideographic characters (Kanji) when drawing strings in any Hershey
  5991. font.  In all, 603 Kanji are available; these are the same Kanji that
  5992. are available in the HersheyEUC font.  The Japanese characters are
  5993. indexed according to the JIS X0208 standard for Japanese typography,
  5994. which represents each character by a two-byte sequence.  The file
  5995. `kanji.doc', which is distributed along with the GNU plotting
  5996. utilities, lists the available Kanji.  On most systems it is installed
  5997. in `/usr/share/libplot' or `/usr/local/share/libplot'.
  5998.    Each JIS X0208 character would be specified by an escape sequence
  5999. which expresses this two-byte sequence as four hexadecimal digits, such
  6000. as "\#J357e".  Both bytes must be in the `0x21'...`0x7e' range in order
  6001. to define a JIS X0208 character.  Kanji are located at "\#J3021" and
  6002. above.  Characters appearing elsewhere in the JIS X0208 encoding may be
  6003. accessed similarly.  For example, Hiragana and Katakana are located in
  6004. the "\#J2421"..."\#J257e" range, and Roman characters in the
  6005. "\#J2321"..."\#J237e" range.  The file `kana.doc', which is installed
  6006. in the same directory as `kanji.doc', lists the encodings of the
  6007. Hiragana and Katakana.  For more on the JIS X0208 standard, see Ken
  6008. Lunde's `Understanding Japanese Information Processing' (O'Reilly,
  6009. 1993), and his on-line supplement (http://www.ora.com/people/authors/lunde/cjk_inf.html).
  6010.    The Kanji numbering used in A. N. Nelson's `Modern Reader's
  6011. Japanese-English Character Dictionary', a longtime standard, is also
  6012. supported.  (This dictionary is published by C. E. Tuttle and Co., with
  6013. ISBN 0-8048-0408-7.  A revised edition [ISBN 0-8048-2036-8] appeared in
  6014. 1997, but uses a different numbering.)  `Nelson' escape sequences for
  6015. Kanji are similar to JIS X0208 escape sequences, but use four decimal
  6016. instead of four hexadecimal digits.  The file `kanji.doc' gives the
  6017. correspondence between the JIS numbering scheme and the Nelson
  6018. numbering scheme.  For example, "\#N0001" is equivalent to "\#J306c".
  6019. It also gives the positions of the available Kanji in the Unicode
  6020. encoding.
  6021.    All available Kanji have the same width, which is the same as that of
  6022. the syllabic Japanese characters (Hiragana and Katakana).  Each Kanji
  6023. that is not available will print as an `undefined character' glyph (a
  6024. set of horizontal lines).  The same is true for non-Kanji JIS X0208
  6025. characters that are not available.
  6026. File: plotutils.info,  Node: Marker Symbols,  Prev: Text String Format,  Up: Text and Markers
  6027. Available marker symbols
  6028. ========================
  6029.    The GNU `libplot' library supports a standard set of marker symbols,
  6030. numbered 0 through 31.  These are the symbols that the `graph' program
  6031. will plot at each point of a dataset, if the `-S' option is used.  The
  6032. list is as follows (by convention, marker symbol #0 means no symbol
  6033. at all).
  6034.   1. dot
  6035.   2. plus (+)
  6036.   3. asterisk (*)
  6037.   4. circle
  6038.   5. cross
  6039.   6. square
  6040.   7. triangle
  6041.   8. diamond
  6042.   9. star
  6043.  10. inverted triangle
  6044.  11. starburst
  6045.  12. fancy plus
  6046.  13. fancy cross
  6047.  14. fancy square
  6048.  15. fancy diamond
  6049.  16. filled circle
  6050.  17. filled square
  6051.  18. filled triangle
  6052.  19. filled diamond
  6053.  20. filled inverted triangle
  6054.  21. filled fancy square
  6055.  22. filled fancy diamond
  6056.  23. half filled circle
  6057.  24. half filled square
  6058.  25. half filled triangle
  6059.  26. half filled diamond
  6060.  27. half filled inverted triangle
  6061.  28. half filled fancy square
  6062.  29. half filled fancy diamond
  6063.  30. octagon
  6064.  31. filled octagon
  6065. The interpretation of marker symbols 1 through 5 is the same as in the
  6066. well known GKS (Graphical Kernel System).
  6067.    Symbols 32 and up are interpreted as characters in a certain text
  6068. font.  For `libplot', it is the current font.  For `graph', it is the
  6069. font selected with the `--symbol-font-name' option.  By default, this
  6070. is the ZapfDingbats font except in `graph -T hpgl' and `graph -T tek'.
  6071. `graph -T hpgl' and `graph -T tek' currently have no access to
  6072. Postscript fonts, so they use the `HersheySerif' font instead.
  6073.    Many of the characters in the ZapfDingbats font are suitable for use
  6074. as marker symbols.  For example, character #74 is the Texas star.  Doing
  6075.      echo 0 0 1 2 2 1 3 2 4 0 | graph -T ps -m 0 -S 74 0.1 > plot.ps
  6076. will produce a Postscript plot consisting of five data points, not
  6077. joined by line segments.  Each data point will be marked by a Texas
  6078. star, of a large font size (0.1 times the width of the plotting box).
  6079.    If you are using `graph -T hpgl' and wish to use font characters as
  6080. marker symbols, you should consider using the Wingdings font, which is
  6081. available when producing HP-GL/2 output.  Doing
  6082.      echo 0 0 1 2 2 1 3 2 4 0 |
  6083.          graph -T hpgl -m 0 --symbol-font Wingdings -S 181 0.1 > plot.plt
  6084. will produce an HP-GL/2 plot that is similar to the preceding Postscript
  6085. plot.  The Wingdings font has the Texas star in location #181.
  6086. File: plotutils.info,  Node: Color Names,  Next: Metafiles,  Prev: Text and Markers,  Up: Appendices
  6087. Specifying Colors by Name
  6088. *************************
  6089.    Many of the plotting utilities allow colors to be specified by name.
  6090. For example, `graph' supports the `--frame-color' option.  `graph -T
  6091. hpgl' and `plot -T hpgl' check the value of the `HPGL_PENS' environment
  6092. variable, as do the HP-GL Plotters available in the `libplot' library.
  6093. Also, the `libplot' library includes the `pencolorname',
  6094. `fillcolorname', and `bgcolorname' functions.
  6095.    In any of these contexts, 665 distinct color names are recognized,
  6096. including obscure ones like "dark magenta", "forest green", and "olive
  6097. drab".  Color names are case-insensitive, and spaces are ignored.  So,
  6098. for example, "RosyBrown" is equivalent to "rosy brown", and
  6099. "DarkGoldenrod3" to "dark goldenrod 3".
  6100.    The file `colors.txt', which is distributed along with the GNU
  6101. plotting utilities, lists the available color names.  On most systems
  6102. it is installed in `/usr/share/libplot' or `/usr/local/share/libplot'.
  6103. The color names are essentially those recognized by recent releases of
  6104. the X Window System, which on most machines are listed in the file
  6105. `/usr/lib/X11/rgb.txt'.  However, for every color name containing the
  6106. string "gray", a version containing "grey" has been included.  For
  6107. example, both "dark slate gray 4" and "dark slate grey 4" are
  6108. recognized color names.
  6109. File: plotutils.info,  Node: Metafiles,  Next: Auxiliary Software,  Prev: Color Names,  Up: Appendices
  6110. The Graphics Metafile Format
  6111. ****************************
  6112.    GNU metafile format is produced by the raw variants of `graph',
  6113. `plot', `tek2plot', and plotfont, and by any other graphics application
  6114. that uses the Metafile Plotter support contained in GNU `libplot'.
  6115. A file in this format is a sort of audit trail: a sequence of plotting
  6116. commands, each of which may be followed by data.  Each plotting command
  6117. is an `op code': a single ASCII character, indicating a Plotter
  6118. operation.  The data following the command are the arguments passed to
  6119. the operation, if any.
  6120.    There are two sorts of GNU metafile: binary (the default) and
  6121. portable (human-readable).  Binary metafiles begin with the magic string
  6122. "#PLOT 1\n", and portable metafiles with the magic string "#PLOT 2\n".
  6123. If you wish to transfer metafiles between machines of different types,
  6124. you should use portable rather than binary format.  Portable metafiles
  6125. are produced by GNU `graph' and the other plotting utilities if the
  6126. `-O' option is specified, and by Metafile Plotters if the
  6127. `META_PORTABLE' parameter is set to "yes".  Both binary and portable
  6128. metafiles can be translated to other formats by GNU `plot'.
  6129.    In the portable format, the arguments of each operation (integers,
  6130. floating point numbers, or strings) are printed in a human-readable
  6131. form, separated by spaces, and each argument list ends with a newline.
  6132. In the binary format, the arguments are represented as integers, single
  6133. precision floating point numbers, or newline-terminated ASCII strings.
  6134. Using the newline character as a terminator is acceptable because each
  6135. `libplot' operation includes a maximum of one string among its
  6136. arguments, and such a string may not include a newline.  Also, the
  6137. string must come last among the arguments.
  6138.    The `openpl' and `closepl' operations open and close a Plotter,
  6139. i.e., begin and end a page of graphics.  They are represented by the
  6140. op codes `o' and `x', respectively.  Each of the other 79 Plotter
  6141. operations has a corresponding op code, with 10 exceptions.  These
  6142. exceptions include (1) the setup operations `flushpl' and `outfile',
  6143. (2) the operations `havecap', `labelwidth', and `flabelwidth', which
  6144. merely return information, and (3) the `colorname', `pencolorname',
  6145. `fillcolorname', and `bgcolorname' operations, which are internally
  6146. mapped to `pencolor', `fillcolor', and `bgcolor', and (4) the
  6147. `ffontname' operation, which in a metafile would be indistinguishable
  6148. from `fontname'.  So besides `o' and `x', there are 69 possible
  6149. op codes, for a total of 71.  The following table lists 10 of the
  6150. op codes other than `o' and `x', followed by the name of the `libplot'
  6151. operation they stand for.
  6152. Op Code
  6153.      Operation
  6154.      `arc'
  6155.      `circle'
  6156.      `erase'
  6157.      `linemod'
  6158.      `line'
  6159.      `move'
  6160.      `cont'
  6161.      `point'
  6162.      `space'
  6163.      `label'
  6164. The full set of 71 op codes is listed in the header file `plot.h',
  6165. which is distributed along with the plotting utilities.  On most
  6166. systems it is installed in `/usr/include' or `/usr/local/include'.
  6167.    It is worth noting that of the 71 op codes, only 46 are used in
  6168. portable metafiles.  That is because in ASCII format, there is no point
  6169. in distinguishing the floating point `libplot' operations from their
  6170. integer counterparts.
  6171.    The 10 op codes in the table above are actually the op codes of the
  6172. traditional `plot(5)' format produced by pre-GNU versions of `graph'
  6173. and `libplot'.  The use of these op codes make GNU metafile format
  6174. compatible with plot(5) format.  The absence of a magic string, and of
  6175. the `o' and `x' op codes, makes it possible to distinguish files in
  6176. plot(5) format from GNU metafiles.  GNU `plot' can convert files in
  6177. plot(5) format to GNU metafiles in either binary or portable format.
  6178. File: plotutils.info,  Node: Auxiliary Software,  Next: Acknowledgements,  Prev: Metafiles,  Up: Appendices
  6179. Obtaining Auxiliary Software
  6180. ****************************
  6181. * Menu:
  6182. * idraw::       Obtaining the idraw drawing editor
  6183. * xfig::        Obtaining the xfig drawing editor
  6184. File: plotutils.info,  Node: idraw,  Next: xfig,  Prev: Auxiliary Software,  Up: Auxiliary Software
  6185. How to get `idraw'
  6186. ==================
  6187.    The `idraw' utility mentioned several times in this documentation is
  6188. a freely distributable interactive drawing editor for the X Window
  6189. System.  It may be used to edit the output of `graph -T ps', or, in
  6190. general, the output of any application that uses the Postscript Plotter
  6191. support contained in `libplot'.
  6192.    The current version of `idraw' is maintained by Vectaport, Inc., and
  6193. is available at their Web site (http://www.vectaport.com).  It is part
  6194. of the `ivtools' package, which is a framework for building custom
  6195. drawing editors.  `idraw' was originally part of the `InterViews'
  6196. package, developed by Stanford University and Silicon Graphics.  The
  6197. `InterViews' package is available at a distribution site (ftp://interviews.stanford.edu) but is no longer supported.  Retrieving the
  6198. `ivtools' package instead is recommended.
  6199.    Also available at Vectaport's Web site (http://www.vectaport.com) is
  6200. an enhanced version of `idraw' called `drawtool'.  Unlike `idraw',
  6201. `drawtool' can import bitmapped graphics in PBM/PGM/PPM, TIFF, and X11
  6202. bitmap formats.
  6203. File: plotutils.info,  Node: xfig,  Prev: idraw,  Up: Auxiliary Software
  6204. How to get `xfig'
  6205. =================
  6206.    The `xfig' utility mentioned several times in this documentation is
  6207. a freely distributable interactive drawing editor for the X Window
  6208. System.  It may be used to edit the output of `graph -T fig', or
  6209. in general the output of any application that uses the Fig Plotter
  6210. support contained in `libplot'.
  6211.    The current version is available at
  6212. `ftp://ftp.x.org/contrib/applications/drawing_tools/'.  It can import
  6213. graphics in GIF, X11 bitmap, and Postscript formats.  Accompanying the
  6214. editor is a package called `transfig', which allows `xfig' graphics to
  6215. be exported in many formats.  GIF, X11 bitmap, LaTeX, and Postscript
  6216. formats are supported.
  6217.    There is a Web page on Fig format (http://duke.usask.ca/~macphed/soft/fig), which discusses application software packages that can
  6218. interoperate with `xfig'.
  6219. File: plotutils.info,  Node: Acknowledgements,  Prev: Auxiliary Software,  Up: Appendices
  6220. Acknowledgements
  6221. ****************
  6222.    Several of the GNU plotting utilities were inspired by Unix plotting
  6223. utilities.  A `graph' utility and various plot filters were present in
  6224. the first releases of Unix from Bell Laboratories, going at least as
  6225. far back as the Version 4 distribution (1973).  Most of the work on
  6226. tying them together and breaking out device-dependent versions of
  6227. `libplot' was performed by Lorinda Cherry <llc@research.att.com>.  By
  6228. the time of Version 7 Unix (1979) and the subsequent Berkeley releases,
  6229. the package consisting of `graph', `plot', `spline', and several
  6230. device-dependent versions of `libplot' was a standard Unix feature.
  6231. The first display device supported by the package was a Versatec
  6232. storage scope.  By the early 1980's, supported devices included
  6233. Tektronix storage scopes, 200dpi electrostatic printer/plotters from
  6234. Versatec and Varian, pen plotters from Hewlett-Packard, and early
  6235. graphics terminals.
  6236.    In 1989, Rich Murphey <rich@freebsd.org> wrote the first GNU
  6237. versions of `graph', `plot', and `spline', and the earliest
  6238. documentation.  Richard Stallman further directed development of the
  6239. programs and provided editorial support for the documentation.
  6240. John Interrante <interran@uluru.stanford.edu>, of the InterViews team
  6241. at Stanford, generously provided the `idraw' Postscript prologue now
  6242. included in `libplot', and helpful comments.  The package as it stood
  6243. in 1991 was distributed under the name `GNU graphics'.
  6244.    In 1995 Robert Maier <rsm@math.arizona.edu> took over development of
  6245. the package, and designed and wrote the current, maximally
  6246. device-independent, standalone version of `libplot'.  He also rewrote
  6247. `graph' from scratch, turning it into a real-time filter that would use
  6248. the new library.  He fleshed out `spline' too, by adding support for
  6249. splines in tension, periodicity, and cubic Bessel interpolation.
  6250.    Most development work on `ode' was performed by Nick Tufillaro <nbt@reed.edu> in 1978-1994, on a sequence of platforms that extended back
  6251. to a PDP-11 running Version 4 Unix.  In 1997 Robert modified Nick's
  6252. 1994 version to agree with GNU conventions on coding and command-line
  6253. parsing, extended it to support the full set of special functions
  6254. supported by `gnuplot', and extended the exception handling.
  6255.    Many other people aided the development of the plotting utilities
  6256. package along the way.  The Hershey vector fonts now in `libplot' are
  6257. of course based on the characters digitized in the mid to late 1960's
  6258. by Allen V. Hershey, who deserves a vote of thanks.  Additional
  6259. characters and/or marker symbols were taken from the SLAC Unified
  6260. Graphics System developed by Robert C. Beach in the mid-1970's, and
  6261. from the fonts designed by Thomas Wolff <wolff@inf.fu-berlin.de> for
  6262. Ghostscript.  The interpolation algorithms used in `spline' are based
  6263. on the algorithms of Alan K. Cline <cline@cs.utexas.edu>, as described
  6264. in his papers in the Apr. 1974 issue of `Communications of the ACM'.
  6265. The table-driven parser used in `tek2plot' was written at Berkeley in
  6266. the mid-1980's by Edward Moy <moy@parc.xerox.com>.  The `sagitta'
  6267. algorithm used in an extended form in `libplot' for drawing circular
  6268. and elliptic arcs was developed by Peter Karnow of URW and
  6269. Ken Turkowski <turk@apple.com> of Apple.  Ray Toy <toy@rtp.ericsson.se>
  6270. helped with the tick mark spacing code in `graph' and was the first to
  6271. incorporate GNU `getopt'.  Arthur Smith, formerly of LASSP at Cornell,
  6272. provided code for his `xplot' utility.  Nelson Beebe <beebe@math.utah.edu> exhaustively tested the package installation process.
  6273.    Robert Maier wrote the documentation, which now incorporates Nick
  6274. Tufillaro's `ode' manual.  Julie Sussmann checked over the
  6275. documentation for style and clarity.
  6276. Tag Table:
  6277. Node: Top
  6278. Node: Plotutils Intro
  6279. Node: graph
  6280. 10299
  6281. Node: Simple Examples
  6282. 11108
  6283. Node: Non-Square Plots
  6284. 23541
  6285. Node: Multiple Datasets
  6286. 26256
  6287. Node: Multiplotting
  6288. 31873
  6289. Node: Data Formats
  6290. 35458
  6291. Node: graph Invocation
  6292. 38186
  6293. Node: Plot Options
  6294. 39781
  6295. Node: Dataset Options
  6296. 55569
  6297. Node: Multiplot Options
  6298. 64779
  6299. Node: Raw graph Options
  6300. 66507
  6301. Node: Info Options
  6302. 67218
  6303. Node: graph Environment
  6304. 68520
  6305. Node: plot
  6306. 73992
  6307. Node: plot Examples
  6308. 74259
  6309. Node: plot Invocation
  6310. 76482
  6311. Node: plot Environment
  6312. 87215
  6313. Node: tek2plot
  6314. 92642
  6315. Node: tek2plot Introduction
  6316. 92939
  6317. Node: tek2plot Invocation
  6318. 94283
  6319. Node: tek2plot Environment
  6320. 104317
  6321. Node: plotfont
  6322. 108203
  6323. Node: plotfont Examples
  6324. 108496
  6325. Node: plotfont Invocation
  6326. 111942
  6327. Node: plotfont Environment
  6328. 119990
  6329. Node: spline
  6330. 124711
  6331. Node: spline Examples
  6332. 124989
  6333. Node: Advanced Use of spline
  6334. 132109
  6335. Node: spline Invocation
  6336. 136646
  6337. Node: ode
  6338. 146138
  6339. Node: Basic Math
  6340. 147472
  6341. Node: Simple ode Examples
  6342. 150354
  6343. Node: Additional ode Examples
  6344. 159416
  6345. Node: ode Invocation
  6346. 166416
  6347. Node: Diagnostics
  6348. 170467
  6349. Node: Numerical Error
  6350. 174586
  6351. Node: Running Time
  6352. 186349
  6353. Node: Input Language
  6354. 187678
  6355. Node: ODE Bibliography
  6356. 196037
  6357. Node: libplot
  6358. 196961
  6359. Node: libplot Overview
  6360. 197340
  6361. Node: C Programming
  6362. 206907
  6363. Node: The C API
  6364. 207371
  6365. Node: C Compiling and Linking
  6366. 213146
  6367. Node: Sample C Drawings
  6368. 214843
  6369. Node: Sample C Animations
  6370. 224906
  6371. Node: X Programming
  6372. 232481
  6373. Node: Functions
  6374. 238930
  6375. Node: Setup Functions
  6376. 240563
  6377. Node: Drawing Functions
  6378. 247101
  6379. Node: Attribute Functions
  6380. 257879
  6381. Node: Mapping Functions
  6382. 269311
  6383. Node: Driver Parameters
  6384. 271454
  6385. Node: Appendices
  6386. 284176
  6387. Node: Text and Markers
  6388. 284633
  6389. Node: Text Fonts
  6390. 285437
  6391. Node: Text Fonts in X
  6392. 295813
  6393. Node: Text String Format
  6394. 298993
  6395. Node: Marker Symbols
  6396. 317310
  6397. Node: Color Names
  6398. 319768
  6399. Node: Metafiles
  6400. 321195
  6401. Node: Auxiliary Software
  6402. 325092
  6403. Node: idraw
  6404. 325373
  6405. Node: xfig
  6406. 326575
  6407. Node: Acknowledgements
  6408. 327496
  6409. End Tag Table
  6410.